Laravel Orion Laravel Package

Getting Started

Start by installing Orion via Composer and generating a resource controller for your first Eloquent model:

composer require tailflow/laravel-orion
php artisan make:orion:controller api/PostController --model=App\Models\Post

Then define routes using the Orion facade—no controller logic required:

// routes/api.php
use Orion\Facades\Orion;

Route::prefix('api')->group(function () {
    Orion::resource('posts', App\Http\Controllers\Api\PostController::class);
});

That’s all it takes for a full REST API: /api/posts now supports GET, POST, PATCH, DELETE, filtering (?filter[title]=Laravel), sorting (?sort=-created_at), pagination (?page=1&per_page=15), and relations (?include=author). The Getting Started guide is the best next step.

Implementation Patterns

Orion thrives on minimal, declarative configuration:

• Authorization: Declare a custom policy class in the controller (protected $policy = PostPolicy::class;) or override viewAny(), view(), store(), etc., directly in the controller.
• Validation: Use a FormRequest (protected $requestClass = StorePostRequest::class;) and rely on $this->validated() when orion.use_validated = true.
• Advanced Filtering: Create filters extending Orion\Http\Filters\Filter and chain nested filters (e.g., ?filter[author.posts.title]=Laravel) or aggregates (?include=posts&aggregate[post_count]=count:posts).
• Custom Queries: Override buildIndexQuery() or buildFetchQuery() to inject scopes or eager loads, and use runIndexFetchQuery($query) for post-processing hooks.
• Relation Resources: Register nested resources by setting $parent = Post::class; and protected $relation = 'comments'; in CommentController to expose /api/posts/{post}/comments.
• OpenAPI Documentation: Auto-generated at /api/docs; customize spec generation by extending Orion\Specs\* classes or injecting a custom Path resolver.

Gotchas and Tips

• Scope Collisions: Before v2.22.4, scopes applied in buildIndexQuery() could be overwritten by filters—always use ≥2.22.4 if leveraging scopes.
• Wildcard Includes: allowedIncludes('*') silently ignores missing or invalid relation methods (e.g., undefined morphTo targets); prefer explicit whitelists (allowedIncludes(['author', 'posts'])) to avoid surprises.
• Pagination Limits: Setting paginationDisabled = true suppresses pagination entirely—use maxPerPage = 50 to enforce safe limits with pagination enabled.
• use_validated Config: If orion.use_validated = true, $this->all() won’t return validated data—ensure your FormRequest’s rules() are strict; enable debug (orion.debug = true) to inspect actual input.
• Nested Relation Inclusion: Deep includes (e.g., ?include=author.posts.comments) require proper relationship chains—2.17.1+ fixes edge-case failures, but ensure models define relations via methods (not dynamic __get).
• Relation Conflict Handling: One-to-one relation stores (e.g., /api/users/{user}/profile) return 409 Conflict when a profile already exists—this is intentional and cannot be bypassed.