Typhoon Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require happytodev/typhoon
   php artisan typhoon:install
   

   This publishes the migration (though Typhoon uses Orbit, not a traditional DB) and sets up the base configuration.

2. First Use Case: Create a content type (e.g., a blog post) via TALL stack (Tailwind, Alpine.js, Laravel, Livewire):

   php artisan typhoon:make:content-type Post
   

   This generates:

   • A Livewire component (PostManager) for managing entries.
   • A Blade view (resources/views/typhoon/posts/index.blade.php).
   • A config file (config/typhoon.php) with default settings.

3. Where to Look First:

   • Orbit Integration: Check config/typhoon.php for Orbit storage paths (e.g., storage/orbit).
   • Livewire Components: All content management lives in app/Http/Livewire/Typhoon/.
   • Views: Content displays are in resources/views/typhoon/.

Implementation Patterns

Core Workflows

1. Content Type Management:

   • Define content types via php artisan typhoon:make:content-type.
   • Customize fields using Orbit’s schema (YAML/JSON) in config/orbit.php or via the TyphoonServiceProvider.
   • Example schema for a Post:

     # config/orbit/posts.yaml
     title: string
     body: markdown
     published_at: datetime
     

2. Livewire Integration:

   • Extend Typhoon\Livewire\ContentManager to add custom logic:

     // app/Http/Livewire/Typhoon/Posts/PostManager.php
     public function mount()
     {
         $this->contentType = 'posts';
         $this->fields = ['title', 'body', 'published_at'];
     }
     

   • Use Alpine.js for dynamic interactions in Blade views (e.g., real-time previews).

3. Displaying Content:

   • Fetch and render content via Orbit’s Orbit::get():

     $posts = Orbit::get('posts')->sortBy('published_at', 'desc');
     

   • Loop through entries in Blade:

     @foreach($posts as $post)
         <h2>{{ $post->title }}</h2>
         {!! $post->body->render() !!} <!-- For markdown -->
     @endforeach
     

4. TALL Stack Synergy:

   • Tailwind: Style managers/views with utility classes (e.g., bg-gray-100).
   • Alpine.js: Add interactivity (e.g., toggling edit modes):

     <div x-data="{ editing: false }">
         <button @click="editing = !editing">Edit</button>
         <div x-show="editing">
             @livewire('typhoon.posts.post-manager')
         </div>
     </div>
     

   • Livewire: Handle form submissions and real-time updates.

Integration Tips

• Filament Navigation: Use filament-navigation to add Typhoon links to Filament admin panels:

  // app/Providers/Filament/AdminPanelProvider.php
  public function panel(Panel $panel): Panel
  {
      return $panel
          ->navigationGroups([
              'Content' => ['resources/views/typhoon/posts/index.blade.php'],
          ]);
  }
  

• Orbit Storage: Configure custom storage paths in config/orbit.php (e.g., S3):

  'storage' => [
      'default' => 's3',
      'disks' => [
          's3' => [
              'driver' => 's3',
              'bucket' => 'your-bucket',
          ],
      ],
  ],
  

• Events: Listen to Orbit events (e.g., Orbit\Events\ContentSaved) for post-processing:

  // app/Providers/EventServiceProvider.php
  public function boot()
  {
      Orbit::listen('posts.*', function ($event) {
          // Trigger webhooks, analytics, etc.
      });
  }
  

Gotchas and Tips

Pitfalls

1. Orbit Schema Mismatches:

   • If the Orbit schema changes (e.g., adding a new field), run:

     php artisan orbit:migrate
     

   • Tip: Use php artisan orbit:dump to inspect current schemas.

2. Livewire Caching:

   • Typhoon’s Livewire components cache aggressively. Clear views when making changes:

     php artisan view:clear
     php artisan cache:clear
     

3. Markdown Rendering:

   • Ensure parsedown/parsedown is installed for markdown support:

     composer require parsedown/parsedown
     

   • Gotcha: Custom markdown extensions (e.g., tables) may require additional packages like michelf/php-markdown.

4. Filament Conflicts:

   • If using Filament, avoid naming Typhoon resources to clash with Filament’s conventions (e.g., PostResource vs. PostsManager).

Debugging

• Orbit Logs: Enable Orbit logging in config/orbit.php:

  'logging' => true,
  

  Check storage/logs/typhoon.log for schema/operation errors.

• Livewire Debugging:

  • Use dd($this->content) in Livewire components to inspect data.
  • Check browser console for Alpine.js errors (e.g., x-data syntax).

Extension Points

1. Custom Field Types:

   • Extend Orbit’s field types by publishing and modifying:

     php artisan vendor:publish --tag=orbit-fields
     

   • Add logic in app/Orbit/Fields/CustomField.php.

2. Orbit Events:

   • Subscribe to events in app/Providers/EventServiceProvider.php:

     Orbit::listen('posts.created', function ($content) {
         // Send notification, etc.
     });
     

3. API Endpoints:

   • Create API routes for content:

     // routes/api.php
     Route::get('/posts', function () {
         return Orbit::get('posts');
     });
     

   • Use Orbit::find() for single entries.

4. Multi-Tenant Support:

   • Override Orbit’s storage path per tenant:

     Orbit::useStorage('tenant_' . auth()->id());