Permission and authorization design in PHP is not solved with a screen where roles are assigned. The problem emerges when the same action depends on who performs it, which organization they work for, which data they act on, and the state of that data. If those conditions are scattered across controllers, queries, templates, and interface validations, the system ends up accumulating exceptions that are difficult to review.
The goal should be for every decision to be explicit, repeatable, and verifiable: an identity attempts to perform an operation on a resource within a context, and a policy decides whether it is allowed. This approach turns ambiguous operational rules into technical controls that product, operations, and development can review together.
Separate identity, authorization, and data scope
Authentication answers who the user is: session, credentials, identity provider, or token. Authorization answers what that identity can do. It is not advisable to infer the latter solely from the former or to treat both as a single layer.
A role groups responsibilities, such as organization administrator, support agent, or approver. A permission represents a specific operation, for example invoice.read, invoice.approve, or member.invite. Scope determines which resources that operation applies to: invoices for an organization, records for a unit, or one's own records.
This distinction prevents a common mistake: granting permission to read invoices and assuming that this allows reading any invoice. The policy must still verify whether the resource belongs to the active organization, whether the user is assigned to the relevant unit, and whether the resource state permits the requested action.
Build an access matrix from operations
Before choosing classes or packages, list actual resources and operations. Use business verbs rather than vague labels such as “manage”: create order, view order, correct draft, approve order, cancel order, export orders, or modify members.
For each operation, agree on four elements with the business:
- The protected resource and action.
- The roles that can request it.
- The applicable data scope: organization, unit, owner, portfolio, or assignment.
- The context and state conditions: active organization, valid delegation, operating hours, or document in draft status.
The resulting matrix is not authorization code, but rather a reviewable specification. It also forces pending decisions to be identified. If it states that support can “view orders,” it must specify whether it can view personal data, attachments, closed orders, or information from all organizations.
Prefer small, stable actions
An action that is too broad concentrates privileges and makes least privilege difficult to apply. Separating order.read from order.export, or user.update from user.assign_role, makes it possible to grant access precisely. It is also not advisable to create a permission for every individual case: if the difference depends on the resource, it is usually a policy condition, not a new role.
Choose between roles, permissions, attributes, and context
Simple roles work when there are few stable roles and operations barely depend on the data. They are a good starting point, but become fragile when names such as manager_con_exportacion or supervisor_solo_unidad_norte appear. These combinations encode exceptions as permanent roles.
Explicit permissions are suitable for decoupling responsibilities from roles and for assigning capabilities in a manageable way. Attributes are useful when the decision depends on properties of the subject, resource, or environment: organization, unit, classification, owner, country, or risk level. Contextual rules complete the model when temporary conditions are involved, such as an active delegation or the approval stage.
In practice, a hybrid model is usually more maintainable: roles grant base permissions; a policy evaluates user and resource attributes; and context provides the selected organization or operating channel. The role must not replace data analysis.
Centralize policies and filter data at the source
A PHP application needs a consistent point for expressing decisions. It can be implemented through policy classes, authorization services, or equivalent components in the chosen framework. What matters is that controllers request a decision and that views are not the only barrier.
if (!$authorizer->can($actor, 'order.approve', $order, $context)) {
throw new AccessDeniedException();
}The policy should receive only the data required to decide: identity, operation, resource, and context. Avoid querying global variables or implicitly depending on the current route; that makes rules difficult to test and reuse.
An individual check is not enough on listing screens. If a query returns orders from several organizations and the interface hides some of them afterward, exposure has already occurred. Apply scope in the repository or query layer: filter by authorized organization, permitted unit, or assigned portfolio before loading results. For resources by identifier, verify both the operation and that the resource belongs to the authorized scope.
States and transitions as part of the policy
Sensitive operations often depend on state. An approver can approve a pending order, but not a canceled or already approved one. Model the allowed transition explicitly and validate it again at the point that persists the change. The interface can disable a button for guidance, but the server policy is the effective control.
Avoid permanent exceptions and revealing denials
Generic roles such as “administrator” need clear boundaries. An administrator of an organization should not automatically become a platform administrator. Likewise, an exception such as “can edit this specific record” must have an owner, reason, review date or expiration date, and traceability. If it recurs, a business rule or model attribute is probably missing.
Denials should be useful without revealing sensitive information. For a direct request for another party's resource, a response indistinguishable from the resource not existing is generally preferable. For an action on an already visible resource, it can indicate that permissions are missing without detailing internal rules, assignments, or protected attributes.
Log authorized and denied sensitive actions when they provide operational value: role changes, exports, approvals, delegated access, and configuration changes. The audit trail must include actor, action, resource, organization or context, time, and outcome. Do not log credentials, tokens, or unnecessary personal data.
Test authorization as a product property
Authorization tests must cover allowed and denied decisions. A minimum suite includes: a user with permission in their organization; the same user in another organization; a user without permission; a resource in an invalid state; and a context change, such as removing an assignment or ending a delegation.
Test policies directly because they provide precise diagnostics, and add integration tests to confirm that routes, controllers, queries, and write operations apply the decision. The most dangerous regressions are privilege regressions: adding a role, a route, or a query optimization that unintentionally expands access.
- Verify that a list does not contain resources outside the scope.
- Verify that knowing another party's identifier does not grant access.
- Verify that a state change requires the corresponding policy.
- Verify that removing a permission invalidates the capability on the next request.
Adopt the model in an application with scattered rules
It is not necessary to rewrite the entire system. Start by inventorying routes, commands, scheduled tasks, and export points that modify or expose data. Prioritize high-impact actions and resources shared across organizations. Extract one policy per domain, cover current behavior with tests, and correct rules that grant more access than intended.
Then, replace scattered checks with calls to the authorization service and move scope filtering into queries. Periodically review unused permissions, roles with too many capabilities, expired delegations, and active exceptions. Permission and authorization design in PHP will be maintainable when a new feature can answer, before it is developed, who operates, on which resource, under what conditions, and with what evidence it has been verified.
Checklist for each new module
- Are business operations and their resources defined?
- Does the matrix distinguish permission, scope, and state condition?
- Are policies applied to reads, writes, exports, and non-interactive processes?
- Do queries filter data before passing it to the interface?
- Are there tests for allowed, denied, and cross-organization access?
- Do sensitive actions leave a proportionate and secure audit trail?
