Pyle

Action Policies ​

This page covers Pyle action policies only. Laravel model policies are resolved by Laravel Gate and policy discovery; do not register model policies in pyle.overrides.policies.

Steps to add a policy to an action ​

  1. For a framework action policy override, create an app policy that extends the framework policy and register it in pyle.overrides.policies. For an app-only action policy with no framework counterpart, place an instantiable ActionPolicy subclass under app/Policies/Actions, for example App\Policies\Actions\Order\CreateOrderPolicy.

  2. Override the $codes variable to create the permissions you want. The format is project:model:name, for example storefront:order:create. Each permission is an array so it can carry options such as default and alias. default means the permission is granted to every role when permissions are seeded.

    php
    'storefront:order:create' => [
    'alias' => 'Create Order',
    'default' => true,
]

  3. Run php artisan framework:seed-roles-and-permissions so the permission exists in your database. The command seeds from the action policy manifest, which includes direct framework policies, configured overrides, and app-only policies.

  4. On the action that needs this permission, implement AuthorizableAction. The interface includes:

    php
    public function getRequiredPermissions(): array;

public function validateAuthorization($context = null): void;

  5. A finalized action would look like this.

    php
    use CBOX\Framework\Base\BaseAction;
use CBOX\Framework\Contracts\AuthorizableAction;
use CBOX\Framework\Policies\Actions\Order\CreateOrderPolicy;

class CreateOrder extends BaseAction implements AuthorizableAction
{
    public function handle($fields = [])
    {
        $this->validateAuthorization();
    }

    public function validateAuthorization($context = null): void
    {
        \CBOX::can(policyCollection: $this->getRequiredPermissions());
    }

    public function getRequiredPermissions(): array
    {
        return [CreateOrderPolicy::class];
    }
}

Framework action policy overrides are configured like this:

php
'overrides' => [
    'policies' => [
        \CBOX\Framework\Policies\Actions\Order\UpdateOrderPolicy::class => \App\Policies\Actions\Order\UpdateOrderPolicy::class,
    ],
],

Use direct framework action policy class strings in new PHP code. The manifest resolves those strings to configured app overrides. App-only policies under app/Policies/Actions are discovered by the manifest for permission seeding and legacy alias checks. framework:seed-roles-and-permissions seeds from ActionPolicyManifest::all(), not by iterating generated bindings. CBOX::policy(...) is a deprecated compatibility helper backed by the manifest only and should not be added to new runtime code.

Specific features: ​

  • In a Blade component, @CBOXcan and @unlessCBOXcan accept direct policy class strings, short aliases with or without the Actions/ prefix, nested policy arrays, context, and any: true. Short aliases such as Order/UpdateOrderPolicy are still preferred in Blade. Missing aliases throw before authorization; authorization failures render as false.

    php
    @CBOXcan('Order/UpdateOrderPolicy')
<div class="px-6 py-4">
</div>
@endCBOXcan

  • If you need a specific implementation of how you want to validate the permission / the authorization of the policy you should override the authorize function in your policy and write your custom logic there. In practice it looks like this:

    php
    protected static function authorize($context): bool
{
    $user = \CBOX::getCurrentUser();

    if ($user->can('admin:comment:update') && $context->author_id == $user->id) {
        return true;
    }

    return false;
}

  • If your policy is for a storefront-facing action that allows guests, override the $authRequired variable. When it is false, unauthenticated users skip the preAuthorize and authorize checks.

    php
    protected static bool $authRequired = true;