# 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](https://github.com/Lomkit/laravel-access-control/releases/tag/v0.7.0), 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](https://github.com/Lomkit/laravel-access-control/blob/1.x/UPGRADE.md) 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](https://github.com/Lomkit/laravel-access-control/releases/tag/v0.7.0) 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()`](/essentials/policies#abilities) on the control.
- **Linking a model.** A control is [discovered](/essentials/controls#discovery) 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()`](/essentials/controls#the-access-facade), 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](/essentials/controls#pure-perimeter-lists).
- **Cache.** Run `php artisan access:cache` again after upgrading, or `php artisan optimize` in your deployment. See [Cache and about](/testing-and-tooling/cache-and-about).

## Queries

<warning>

**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](/essentials/queries).

</warning>

- `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](/digging-deeper/batched-decisions).

## Perimeters

- **Abilities.** `allowed()` receives an [`Ability`](/digging-deeper/abilities) 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](/essentials/perimeters).
- **Every row.** A global perimeter becomes `unrestricted()`. See [Unrestricted perimeters](/essentials/perimeters#unrestricted-perimeters).
- **Combining.** Perimeters that stopped at the first allowed one become a [`Levels::of()`](/essentials/levels) 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](/essentials/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()`](/essentials/boundaries) on the control.
- **Parents.** A child whose `query()` called `whereHas()` on its parent becomes a [`ThroughParent`](/essentials/parents), which delegates only `view` by default.

## Policies

- **Automatic policies.** An empty `ControlledPolicy` subclass is replaced by [`Access::registerPolicies()`](/essentials/policies#automatic-policies).
- **Responses.** The policy methods return a `Response` with a [refusal code](/essentials/policies#refusals), 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](/essentials/policies#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](/essentials/policies#decisions-on-the-stored-row).
- **Business abilities.** A method that called the control by hand calls `decideByControl()`. See [Business abilities](/essentials/policies#business-abilities).
- **Decision context.** What `allowed()` reads besides the reader, such as the current team, goes in [`Access::decisionContextUsing()`](/essentials/readers#the-decision-context).

## Search

- **The model.** `Searchable` becomes `ControlledSearchable`, and every search says `controlled()`, `controlledFor()` or `uncontrolled()`. See [Search overview](/search/overview).
- **Search keys.** `scoutQuery()` and `scoutScope()` are replaced by [`searchKeys()`](/search/overview#search-keys). 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](/search/engines).
- **Freshness.** A listener that reindexed documents becomes `reindexWhen()` or the `ReindexesSearch` pivot trait. See [Keeping the keys fresh](/search/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](/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](/integrations/laravel-rest-api).

## Testing and tooling

- **Checks.** Run [`php artisan access:check`](/testing-and-tooling/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](/testing-and-tooling/testing).
- **Generators.** `make:perimeter --overlay` is removed. Publish your stubs again if you published them. See [Generators](/testing-and-tooling/generators).
