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.phpand itsmethodsmap are gone: delete your published file. A custommethodsmap becomes an override ofabilityFor()on the control. - Linking a model. A control is discovered in
app/Access/Controlsby its$model, or named on the model with#[ControlledBy].addControl(),addControls()andAccess::$controlDiscoveryPathsare replaced by the attribute andAccess::discoverControlsIn(), which adds directories. - The
Accessfacade.Access::controlForModel()becomesAccess::controlFor(), which throwsMissingControlException, withAccess::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:cacheagain after upgrading, orphp artisan optimizein 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')andcontrolledFor($user, 'approve')list the rows of another ability.withAbilities(),Access::preload()andreachableKeys()replace the helpers that collected the editable keys. See Batched decisions.
Perimeters
- Abilities.
allowed()receives anAbilityinstead of a string: type the parameterAbility $abilityand compare with$ability->is('update'). - Callbacks. A
query()callback constrains the builder it receives, and an empty or joined one throws. A perimeter withoutshould()checks a saved row in SQL through itsquery(): remove theshould()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, andOverlayPerimeterbecomes a plain perimeter outside the group. - Classes. The overridden
apply*Callback()methods become the protected hooksallows(),includes()andscope(), which receive anAccessContext. 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()orapplyQueryControl()toboundary()on the control. - Parents. A child whose
query()calledwhereHas()on its parent becomes aThroughParent, which delegates onlyviewby default.
Policies
- Automatic policies. An empty
ControlledPolicysubclass is replaced byAccess::registerPolicies(). - Responses. The policy methods return a
Responsewith a refusal code, and a row of another tenant answers404. - Drafts. Authorize a creation with the model about to be created:
authorize('create', [Post::class, $draft]). An overriddencreate()takescreate(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 withunsaved, for every ability butviewAnyandcreate. 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 inAccess::decisionContextUsing().
Search
- The model.
SearchablebecomesControlledSearchable, and every search sayscontrolled(),controlledFor()oruncontrolled(). See Search overview. - Search keys.
scoutQuery()andscoutScope()are replaced bysearchKeys(). A controlled search now gives the union of the perimeters, with the boundary. - Engines. Declare
_accessand_boundaryas filterable, then reindex every controlled model. Thecollectionengine is refused: usedatabase. See Engines. - Freshness. A listener that reindexed documents becomes
reindexWhen()or theReindexesSearchpivot trait. See Keeping the keys fresh. - Browser search. A token whose filter was written by hand becomes
Access::searchToken(), or a route that callsAccess::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.
AccessControlExtensionrestricts the rows, filters the text searches and preloads the row checks of every controlled resource: remove theperimeterQuery()andprepareAuthorization()overrides that applied the control. See laravel-rest-api.
Testing and tooling
- Checks. Run
php artisan access:checkin CI, with the Scout driver of production. - Assertions. A test that compared
can()withcontrolled()by hand becomesassertControlAgrees(). Remove theAccess::flush()calls: each test gets a new registry. See Testing. - Generators.
make:perimeter --overlayis removed. Publish your stubs again if you published them. See Generators.