Evolution Laravel Package

Getting Started

Minimal Setup

1. Install via Composer:

   composer create-project evolution-cms/evolution your-project-name
   

   Follow the CLI prompts to configure the database and basic settings.

2. First Access:

   • Navigate to /manager to log in (default credentials: admin/admin).
   • Run migrations:

     php artisan evolution:migrate
     

3. First Use Case:

   • Create a Resource (page) via the Manager UI under Content > Resources.
   • Use a Chunk (template fragment) to render dynamic content:

     {{ resource.get('content') }}
     

   • Deploy with:

     php artisan evolution:deploy
     

Key Starting Points

• Documentation: /docs (local) or official docs.
• Core Concepts:
  • Resources = Pages/Content.
  • Snippets = Reusable PHP logic.
  • Chunks = Templating fragments (Twig/HTML).
  • Plugins = Event-driven extensions.
• Quick Wins:
  • Override default templates in resources/views/.
  • Use php artisan evolution:make:snippet to scaffold logic.

Implementation Patterns

Core Workflows

1. Content-Driven Development:

   • Dynamic Pages: Use [[*content]] placeholders in Chunks or Twig {{ resource.get('field') }}.
   • Template Inheritance: Extend resources/views/base.twig for site-wide layouts.
   • Example Snippet (getRelatedResources):

     // app/Snippets/getRelatedResources.php
     return Evolution\Resources::where('parent', $resource->id)->get();
     

2. Plugin-Based Extensibility:

   • Event Hooks: Bind to core events (e.g., OnPageNotFound):

     // app/Plugins/Redirect404.php
     public function onPageNotFound() {
         return redirect('/custom-404');
     }
     

   • Register in config/evolution/plugins.php:

     'plugins' => [
         'Redirect404' => true,
     ],
     

3. Multilingual Content:

   • Use tv (Template Variables) for language-specific fields:

     {{ resource.get('title', 'en') }}  {# Fallback to default lang #}
     

   • Override language templates in resources/lang/{locale}/.

4. API Integration:

   • Expose Resources via REST:

     // app/Http/Controllers/Api/ResourcesController.php
     public function index() {
         return Evolution\Resources::all();
     }
     

   • Use evolution:api middleware for authentication.

Integration Tips

• Laravel Synergy:
  • Publish Evolution assets:

    php artisan vendor:publish --tag=evolution-assets
    

  • Use Laravel’s Route::get() alongside Evolution’s [[*path]] routing.
• Frontend Assets:
  • Compile assets with Laravel Mix/Vite; link via Chunks:

    <link href="{{ asset('css/app.css') }}" rel="stylesheet">
    

• Database:
  • Extend evolution_resources table via migrations (e.g., custom_meta column).
  • Use Eloquent models for custom queries:

    class CustomResource extends \Evolution\Resources {
        protected $casts = ['custom_meta' => 'array'];
    }
    

Gotchas and Tips

Pitfalls

1. Caching Quirks:

   • Issue: Chunk/Snippet changes may not reflect immediately due to caching.
   • Fix: Clear cache via Manager (System > Cache) or CLI:

     php artisan evolution:clear-cache
     

   • Pro Tip: Use [[++cache]] in Chunks to disable caching for dynamic content.

2. Twig vs. Legacy Syntax:

   • Gotcha: Mixing [[*placeholders]] with Twig can cause conflicts.
   • Solution: Prefer Twig for new projects; wrap legacy syntax in {% raw %}:

     {% raw %}[[*content]]{% endraw %}
     

3. Plugin Loading Order:

   • Issue: Plugins may override each other unexpectedly.
   • Fix: Set priority in config/evolution/plugins.php:

     'plugins' => [
         'PluginA' => ['priority' => 10],
         'PluginB' => ['priority' => 20],
     ],
     

4. Database Migrations:

   • Gotcha: Running php artisan migrate directly may skip Evolution tables.
   • Fix: Always use:

     php artisan evolution:migrate
     

5. Multilingual SEO:

   • Issue: Duplicate content if language fields are empty.
   • Fix: Use [[+alias]] with language fallbacks:

     <title>{{ resource.get('meta_title', resource.get('title')) }}</title>
     

Debugging

• Enable Debug Mode:

  // config/evolution.php
  'debug' => env('APP_DEBUG', true),
  

• Log Events:

  // In a Plugin/Snippet
  \Evolution\Log::info('Custom event triggered', ['data' => $data]);
  

  Check logs at /manager/system/logs/.

• Common Errors:

  • 404 on Resources: Verify [[*path]] is set in the Resource’s URL.
  • White Screen: Check storage/logs/laravel.log for PHP errors.
  • Permission Denied: Ensure storage/ and bootstrap/cache/ are writable.

Extension Points

1. Custom Fields:

   • Extend Evolution\Fields\FieldType to create reusable input types.
   • Example: Add a ColorPicker field via a module.

2. Event System:

   • Available Events: OnResourceSave, OnWebPagePrerender, OnUserLogin.
   • Listen in app/Events/EvolutionEventServiceProvider.php:

     public function boot() {
         Event::listen('OnResourceSave', function ($resource) {
             // Custom logic
         });
     }
     

3. Theming:

   • Override core templates by copying from vendor/evolution-cms/evolution/resources/views/ to resources/views/.
   • Use {{ parent() }} in Twig to inherit parent template logic.

4. CLI Commands:

   • Extend Evolution’s commands (e.g., evolution:make:snippet) by publishing and overriding:

     php artisan vendor:publish --tag=evolution-commands