Getting Started

Upgrade guide

Move an application from Laravel Access Control 0.x to 1.0, area by area, with a link to the page that explains each new way.

Upgrading to 1.0 from 0.x

Version 1.0 requires PHP 8.3 and Laravel 13. Applications that stay on Laravel 12 can use version 0.7, the last 0.x release.

This page sums up the main changes, area by area, each with the page that explains the new way. The upgrade guide on GitHub lists every breaking change, with before and after examples, and ends with a table that maps each removed call to its replacement. Go through the sections of the features that your application uses.

Coming from 0.6

Version 0.7 already changed several things. If you upgrade from 0.6, apply the 0.7.0 checklist first, then the 1.0 guide.

Configuration and controls

  • No configuration file. config/access-control.php and its methods map are gone: delete your published file. A custom methods map becomes an override of abilityFor() on the control.
  • Linking a model. A control is discovered in app/Access/Controls by its $model, or named on the model with #[ControlledBy]. addControl(), addControls() and Access::$controlDiscoveryPaths are replaced by the attribute and Access::discoverControlsIn(), which adds directories.
  • The Access facade. Access::controlForModel() becomes Access::controlFor(), which throws MissingControlException, with Access::hasControl() to check first. Access::flush() is removed.
  • Pure perimeter lists. A control builds its perimeters once per process: read the user and the request in the callbacks, never in perimeters(). See Pure perimeter lists.
  • Cache. Run php artisan access:cache again after upgrading, or php artisan optimize in your deployment. See Cache and about.

Queries

A query is controlled only when it says so.queries.enabled_by_default is gone: plain queries, relations, whereHas() subqueries, eager and lazy loads and route model binding now read every row unless they call controlled(). Add controlled() to every query that must be filtered, and authorize a model bound to a route through its policy. See Queries.
  • controlled('update') and controlledFor($user, 'approve') list the rows of another ability.
  • withAbilities(), Access::preload() and reachableKeys() replace the helpers that collected the editable keys. See Batched decisions.

Perimeters

  • Abilities. allowed() receives an Ability instead of a string: type the parameter Ability $ability and compare with $ability->is('update').
  • Callbacks. A query() callback constrains the builder it receives, and an empty or joined one throws. A perimeter without should() checks a saved row in SQL through its query(): remove the should() callbacks that only repeated it, and keep those of the perimeters through which users create rows. See Perimeters.
  • Every row. A global perimeter becomes unrestricted(). See Unrestricted perimeters.
  • Combining. Perimeters that stopped at the first allowed one become a Levels::of() group, widest first, and OverlayPerimeter becomes a plain perimeter outside the group.
  • Classes. The overridden apply*Callback() methods become the protected hooks allows(), includes() and scope(), which receive an AccessContext. See Perimeter classes.
  • Immutable. Each fluent method returns a new perimeter, and a second declaration of a callback throws.

Boundaries and parents

  • Boundaries. A condition that every row must meet, such as the tenant, moves from an override of applies() or applyQueryControl() to boundary() on the control.
  • Parents. A child whose query() called whereHas() on its parent becomes a ThroughParent, which delegates only view by default.

Policies

  • Automatic policies. An empty ControlledPolicy subclass is replaced by Access::registerPolicies().
  • Responses. The policy methods return a Response with a refusal code, and a row of another tenant answers 404.
  • Drafts. Authorize a creation with the model about to be created: authorize('create', [Post::class, $draft]). An overridden create() takes create(Model $user, ?Model $draft = null): Response, or PHP throws a fatal error. See Drafts.
  • Stored values. The policy decides a saved row on its stored values: a row changed with fill() is decided on what the database holds, so check new values through a draft. A model that is not saved is refused with unsaved, for every ability but viewAny and create. See Decisions on the stored row.
  • Business abilities. A method that called the control by hand calls decideByControl(). See Business abilities.
  • Decision context. What allowed() reads besides the reader, such as the current team, goes in Access::decisionContextUsing().
  • The model. Searchable becomes ControlledSearchable, and every search says controlled(), controlledFor() or uncontrolled(). See Search overview.
  • Search keys. scoutQuery() and scoutScope() are replaced by searchKeys(). A controlled search now gives the union of the perimeters, with the boundary.
  • Engines. Declare _access and _boundary as filterable, then reindex every controlled model. The collection engine is refused: use database. See Engines.
  • Freshness. A listener that reindexed documents becomes reindexWhen() or the ReindexesSearch pivot trait. See Keeping the keys fresh.
  • Browser search. A token whose filter was written by hand becomes Access::searchToken(), or a route that calls Access::guardSearch(). See Search from the browser.

laravel-rest-api

  • An application that uses laravel-rest-api upgrades it to 3.6 or later first: 1.0 conflicts with earlier versions, so Composer refuses the upgrade until then.
  • AccessControlExtension restricts the rows, filters the text searches and preloads the row checks of every controlled resource: remove the perimeterQuery() and prepareAuthorization() overrides that applied the control. See laravel-rest-api.

Testing and tooling

  • Checks. Run php artisan access:check in CI, with the Scout driver of production.
  • Assertions. A test that compared can() with controlled() by hand becomes assertControlAgrees(). Remove the Access::flush() calls: each test gets a new registry. See Testing.
  • Generators. make:perimeter --overlay is removed. Publish your stubs again if you published them. See Generators.