Getting Started

First Steps

Installation Begin by installing via Composer:

composer require orchid/platform

Then publish the package assets and configuration:

php artisan vendor:publish --provider="Orchid\Platform\Providers\OrchidServiceProvider" --tag="orchid-config"
php artisan vendor:publish --provider="Orchid\Platform\Providers\OrchidServiceProvider" --tag="orchid-migrations"
php artisan vendor:publish --provider="Orchid\Platform\Providers\OrchidServiceProvider" --tag="orchid-assets"

Run migrations:

php artisan migrate

Initial Setup Register the OrchidServiceProvider in config/app.php under providers. Add the middleware to app/Http/Kernel.php:

'web' => [
    \Orchid\Platform\Http\Middleware\HandleOrchidRequest::class,
    // ... other middleware
],

Configure the admin route in routes/web.php:

Route::middleware(['web', 'orchid'])
    ->prefix('admin')
    ->group(base_path('vendor/orchid/platform/src/Routes/admin.php'));

First Use Case: Creating a Screen Scaffold a new screen (dashboard, CRUD, or custom) via Artisan:
```
php artisan orchid:screens Dashboard
```
This generates a DashboardScreen class in app/Screens/DashboardScreen.php. Open it and customize the layout using Orchid’s screen builder.

Implementation Patterns

Core Workflows

Building Screens

Dashboard Screens: Use DashboardScreen for static content (widgets, charts).

public function run()
{
    return view('dashboard')->with([
        'users' => User::count(),
    ]);
}

CRUD Screens: Extend Screens\CrudScreen for dynamic data management.

protected $model = User::class;
protected $columns = ['id', 'name', 'email'];
protected $filters = ['name', 'email'];

Custom Screens: Combine UI components (e.g., TextInput, Modal) for bespoke interfaces.

public function run()
{
    return [
        'title' => 'Custom Screen',
        'users' => User::all(),
        'form' => new Form([
            'name' => '',
            'email' => '',
        ]),
    ];
}

UI Components

Reusable Components: Orchid provides pre-built components (e.g., Alert, Button, Table).

public function run()
{
    return [
        'alert' => new Alert('Success', 'Operation completed!'),
    ];
}

Custom Components: Create reusable widgets by extending Component:

namespace App\Components;
use Orchid\Platform\Component\Component;

class StatsCard extends Component
{
    public $title;
    public $value;

    public function __construct($title, $value)
    {
        $this->title = $title;
        $this->value = $value;
    }
}

Navigation & Permissions

Dynamic Navigation: Define routes and permissions in DashboardServiceProvider:

public function boot()
{
    Dashboard::setBreadcrumbs(fn() => Breadcrumbs::make()->push('Dashboard'));
    Dashboard::setMenu(Menu::make()->add('Users', 'users')->route('users.index'));
}

Role-Based Access: Use can() in screens or middleware:

if (!auth()->user()->can('manage_users')) {
    abort(403);
}

Data Management

Repositories: Orchid includes a base Repository class for Eloquent models.

use Orchid\Platform\Repositories\Repository;

class UserRepository extends Repository
{
    public function scopeActive($query)
    {
        return $query->where('active', true);
    }
}

Filters & Search: Leverage built-in filtering:

protected $filters = ['name', 'email', 'active'];

Assets & Theming
- Custom CSS/JS: Publish assets and override defaults:
```
php artisan vendor:publish --tag="orchid-assets"
```
  Extend resources/css/orchid.css or resources/js/orchid.js.
- Dark Mode: Enable via config:
```
'dark_mode' => env('ORCHID_DARK_MODE', false),
```

Gotchas and Tips

Common Pitfalls

Route Conflicts
- Orchid’s admin routes are prefixed with /admin. Ensure no overlap with frontend routes.
- Fix: Use middleware to restrict access:
```
Route::middleware(['web', 'orchid'])->group(...);
```
Caching Issues
- Orchid caches views and menus. Clear cache after changes:
```
php artisan orchid:cache:clear
```
- Tip: Disable caching in development:
```
'cache' => [
    'enabled' => env('APP_ENV') !== 'local',
],
```

Model Binding

Orchid uses resolveRouteBinding for model resolution. Ensure your models implement it:

public function resolveRouteBinding($value)
{
    return $this->where('slug', $value)->firstOrFail();
}

Permission Denied (403)
- Verify can() checks in screens and middleware. Test with:
```
php artisan orchid:permissions:list
```
Asset Loading
- If CSS/JS fails to load, check:
  - Published assets exist in public/vendor/orchid.
  - No conflicts with Laravel Mix/Vite. Use @orchidScripts and @orchidStyles in layouts.

Debugging Tips

Log Orchid Events: Listen to events in DashboardServiceProvider:

event(new \Orchid\Platform\Events\ScreenRendering('dashboard'));

DD() in Screens: Use dump() or dd() sparingly—Orchid’s debug toolbar (/orchid/toolbar) is more efficient.
Check the Query Log: Enable in .env:
```
DB_LOG_QUERIES=true
```

Extension Points

Custom Screen Types Extend Screen for unique layouts (e.g., MultiStepScreen):

namespace App\Screens;
use Orchid\Platform\Screen\Screen;

class MultiStepScreen extends Screen
{
    public function run()
    {
        return [
            'step1' => new Step1(),
            'step2' => new Step2(),
        ];
    }
}

Override Default Screens Replace Orchid’s default screens (e.g., SettingsScreen) by publishing and modifying:
```
php artisan vendor:publish --tag="orchid-screens"
```
API Integration Use Orchid’s Http\Resources for API-like responses in screens:
```
return [
    'data' => UserResource::collection(User::all()),
];
```
Localization Extend translations by publishing language files:
```
php artisan vendor:publish --tag="orchid-lang"
```
Override in resources/lang/vendor/orchid.

Testing Use Orchid’s test helpers:

use Orchid\Testing\TestCase;

public function testDashboardAccess()
{
    $this->actingAsUser(factory(User::class)->create())
         ->get('/admin')
         ->assertStatus(200);
}

Pro Tips

Use orchid:screen Artisan Commands:

php artisan orchid:screens:list  # List all screens
php artisan orchid:permissions:create role:admin  # Create roles

Leverage orchid:import for bulk data seeding.
Monitor Performance: Orchid’s toolbar shows query/execution time.
Community Plugins: Explore Orchid Marketplace for extensions (e.g., orchid/medialibrary).

Platform Laravel Package