Cms Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require statamic/cms
   

   Requires Laravel 10+ and PHP 8.1+. Follow the official installation guide for full setup.

2. Publish Assets & Config:

   php artisan vendor:publish --provider="Statamic\Providers\StatamicServiceProvider" --tag="config"
   php artisan vendor:publish --provider="Statamic\Providers\StatamicServiceProvider" --tag="migrations"
   php artisan migrate
   

3. First Use Case:

   • Create a collection (php artisan statamic:collection blog) and a blueprint (php artisan statamic:blueprint blog/entry).
   • Add a field (e.g., title, content) to the blueprint.
   • Publish a test entry via the Control Panel (CP) at /admin.

Key Starting Points

• Control Panel: Access at /admin (configured in config/statamic/cp).
• Documentation: Statamic.dev (API reference, fieldtypes, and CP guides).
• CLI Commands:

  php artisan statamic:install       # Full setup
  php artisan statamic:blueprint    # Generate blueprints
  php artisan statamic:collection   # Create collections
  php artisan statamic:fieldtype    # Register custom fieldtypes
  

Implementation Patterns

Core Workflows

1. Content Modeling

• Collections: Organize content (e.g., blog, products) with php artisan statamic:collection.

  // config/statamic/collections.php
  'blog' => [
      'title' => 'Blog',
      'singular' => 'Entry',
      'entries' => 'entries',
      'blueprint' => 'blog/entry',
  ],
  

• Blueprints: Define fields for entries (YAML/JSON/Blade).

  # resources/blueprints/collections/blog/entry.yaml
  title: Title
  content:
    type: bard
    display: Content
  

• Fieldtypes: Use built-in types (text, bard, assets, relationships) or extend with custom fieldtypes.

2. Content Retrieval

• Antlers Templating (Statamic’s native syntax):

  {{ entries for="blog" sort="date:desc" limit="5" }}
      <h2>{{ title }}</h2>
      {{ content }}
  {{ /entries }}
  

• Laravel Eloquent:

  use Statamic\Entries\Entry;
  
  $entries = Entry::query()
      ->where('collection', 'blog')
      ->sortBy('date', 'desc')
      ->limit(5)
      ->get();
  

• GraphQL API (v6.8+):

  query {
    entries(collection: "blog", sort: "date:desc", limit: 5) {
      title
      content
    }
  }
  

3. Assets Management

• Uploads: Drag-and-drop via CP or php artisan statamic:upload.
• Querying:

  use Statamic\Assets\Asset;
  
  $assets = Asset::query()
      ->where('container', 'images')
      ->where('folder', 'headers')
      ->get();
  

• URLs:

  {{ asset_url asset }}
  {{ asset_width asset }}x{{ asset_height asset }}
  

4. Customization

• Extend CP: Override Blade views in resources/views/vendor/statamic.
• Custom Fieldtypes:

  php artisan statamic:fieldtype my_fieldtype
  

  // app/Fieldtypes/MyFieldtype.php
  namespace App\Fieldtypes;
  
  use Statamic\Fieldtypes\Fieldtype;
  
  class MyFieldtype extends Fieldtype {
      public static function fieldtype(): string {
          return 'my_fieldtype';
      }
  }
  

• Navigation: Define in config/statamic/navigation.php or via CP.

5. Localization

• Multi-Language: Enable in config/statamic/localization.

  'locales' => [
      'en' => 'English',
      'es' => 'Spanish',
  ],
  

• Fallbacks: Use {{ locale }} in Antlers or app()->getLocale() in PHP.

6. Workflows

• Revisions: Enable in blueprints (revisions: true).
• Drafts/Publish: Use {{ is_draft }} or entry->isPublished().
• Scheduled Publishing: Set date field in blueprint.

Integration Tips

Laravel Ecosystem

• Service Providers: Register Statamic bindings:

  $this->app->singleton('statamic', function () {
      return app(Statamic::class);
  });
  

• Middleware: Protect routes:

  Route::middleware(['web', 'statamic.cp'])->group(function () {
      // CP routes
  });
  

• Events: Listen to content changes:

  Event::listen(EntrySaved::class, function (EntrySaved $event) {
      // Handle saved entry
  });
  

Frontend Integration

• Live Preview: Use {{ livepreview_token }} in Antlers.
• Static Site Generation: Cache entries with php artisan statamic:cache.
• Tailwind CSS: Statamic includes Tailwind by default. Extend in resources/css/statamic.css.

Performance

• Caching: Clear cache with:

  php artisan statamic:cache:clear
  php artisan statamic:cache:clear --collections
  

• Asset Optimization: Use php artisan statamic:optimize.

Gotchas and Tips

Pitfalls

1. Fieldtype Validation:

   • Custom fieldtypes must implement validate() and return null or ValidationException.
   • Example:

     public function validate($value, $field, $errors, $data) {
         if (empty($value)) {
             $errors->add($field->handle(), 'This field is required.');
         }
         return $errors;
     }
     

2. Antlers Parsing:

   • Double Curly Braces: Escape with {{{ or }}}.
   • Partial Parsing: Use {{ partial }} carefully—it parses Antlers recursively.
   • Debugging: Enable Antlers debugging in config/statamic/antlers.php:

     'debug' => env('APP_DEBUG', false),
     

3. Asset Handling:

   • Container Permissions: Ensure storage/app/assets is writable.
   • Unique Filenames: Use Asset::moveUnique() to avoid conflicts:

     $asset->moveUnique();
     

   • SVG Sanitization: Statamic sanitizes SVGs on upload. For custom handling, use Statamic\Assets\Asset::sanitizeSvg().

4. Localization Quirks:

   • Fallbacks: Always define a default locale in config/statamic/localization.
   • Date Formats: Override in config/statamic/localization.php:

     'date_formats' => [
         'en' => 'm/d/Y',
         'es' => 'd/m/Y',
     ],
     

5. CP Navigation:

   • Active State: Use active class in navigation YAML:

     items:
       - url: /admin/collections/blog
         title: Blog
         active: true
     

   • Trailing Slashes: Ensure APP_URL in .env matches CP routes (e.g., APP_URL=https://example.com).

6. Blueprints:

   • Field Order: Use order in YAML to control display:

     fields:
       title:
         order: 1
       content:
         order: 2
     

   • Conditional Fields: Use display logic:

     fields:
       featured_image:
         display: "{{ featured == true }}"
     

7. Replicator Fields:

   • Drag & Drop: Ensure handle is unique for each set in the replicator:

     fields:
       items:
         type: replicator
         sets:
           item:
             fields:
               title:
                 handle: title_{{ index }}  # Unique handle
     

8. GraphQL:

   • Authentication: Requires statamic.pro for advanced features (v6.8+).
   • Query Limits: Default limits apply (e.g., limit: 100).

Debugging Tips

1. CP Errors:

   • Check storage/logs/statamic.log for CP-specific errors.
   • Enable debug mode in config/statamic/cp.php:

     'debug' => true,
     

2. **Antlers