Articlebundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require altuma/articlebundle
   

   Add to config/app.php under providers:

   Altuma\ArticleBundle\ArticleBundleServiceProvider::class,
   

   Publish the bundle's migrations and config:

   php artisan vendor:publish --provider="Altuma\ArticleBundle\ArticleBundleServiceProvider" --tag="migrations"
   php artisan vendor:publish --provider="Altuma\ArticleBundle\ArticleBundleServiceProvider" --tag="config"
   

   Run migrations:

   php artisan migrate
   

2. First Use Case: Creating an Article Use the Article model (auto-registered via the service provider):

   use Altuma\ArticleBundle\Models\Article;
   
   $article = Article::create([
       'title' => 'My First Article',
       'slug' => 'my-first-article',
       'content' => '<p>Hello, world!</p>',
       'status' => 'published', // or 'draft', 'archived'
   ]);
   

3. Key Config Check config/article.php for default settings like:

   • default_status
   • allowed_statuses
   • content_editor (e.g., ckeditor, tinymce)

Implementation Patterns

Core Workflows

1. CRUD Operations Use Eloquent methods directly on the Article model:

   // Fetch published articles
   $articles = Article::where('status', 'published')->latest()->get();
   
   // Update article
   $article->update(['content' => '<p>Updated content</p>']);
   

2. Slug Generation Auto-generate slugs via the sluggable trait (if enabled in config):

   $article = Article::create([
       'title' => 'New Article',
       // Slug auto-generated from title
   ]);
   

3. Status Transitions Use the changeStatus() method to handle workflows:

   $article->changeStatus('draft'); // Validates against allowed_statuses
   

4. Content Management Integrate with editors via the content field (e.g., CKEditor):

   // In a form request
   $validated = $request->validate([
       'content' => 'required|string',
   ]);
   

5. API Integration Use Laravel's API resources:

   php artisan make:resource ArticleResource
   

   Then:

   return new ArticleResource(Article::paginate(10));
   

Advanced Patterns

1. Custom Fields Extend the Article model or use morph maps for custom field types:

   // Example: Add a 'featured_image' field
   $article->update(['featured_image' => 'path/to/image.jpg']);
   

2. Event Listeners Listen to article events (e.g., ArticlePublished):

   // In EventServiceProvider
   protected $listen = [
       'Altuma\ArticleBundle\Events\ArticlePublished' => [
           'App\Listeners\SendArticleNotification',
       ],
   ];
   

3. Policy Integration Define policies for authorization:

   php artisan make:policy ArticlePolicy --model=Article
   

   Then restrict access:

   $this->authorize('update', $article);
   

4. Tagging/Categorization Use many-to-many relationships (if the bundle supports it):

   $article->categories()->attach([1, 2, 3]);
   

5. SEO Optimization Leverage the meta_title and meta_description fields:

   $article->update([
       'meta_title' => 'SEO Title',
       'meta_description' => 'SEO Description',
   ]);
   

Gotchas and Tips

Common Pitfalls

1. Slug Conflicts

   • Ensure slug is unique. Use Str::slug() manually if auto-generation fails:

     $slug = Str::slug($title).'-'.time();
     

2. Status Validation

   • The changeStatus() method enforces allowed_statuses in config. Override the trait if custom logic is needed:

     public function changeStatus($status) {
         if (!in_array($status, $this->getAllowedStatuses())) {
             throw new \InvalidArgumentException("Invalid status: {$status}");
         }
         $this->status = $status;
         $this->save();
     }
     

3. Content Editor Integration

   • If using a custom editor, ensure the content field is saved as HTML. Sanitize input to prevent XSS:

     use Purifier;
     $cleanContent = Purifier::clean($request->content);
     

4. Migration Conflicts

   • If extending the articles table, run:

     php artisan migrate:fresh --env=testing
     

     in a test environment to avoid conflicts.

5. Caching Headaches

   • Clear the route cache if adding new routes:

     php artisan route:clear
     

Pro Tips

1. Bulk Actions Use query builder for bulk updates:

   Article::where('status', 'draft')->update(['status' => 'published']);
   

2. Soft Deletes Enable soft deletes in the model:

   use SoftDeletes;
   class Article extends Model {
       use SoftDeletes;
       protected $dates = ['deleted_at'];
   }
   

3. Localization Store translations in a translations JSON column:

   $article->update([
       'translations' => json_encode([
           'en' => ['title' => 'English Title'],
           'fr' => ['title' => 'Titre Français'],
       ]),
   ]);
   

4. Testing Use factories for testing:

   php artisan make:factory ArticleFactory --model=Article
   

   Example factory:

   $factory->define(Article::class, function (Faker $faker) {
       return [
           'title' => $faker->sentence,
           'slug' => $faker->slug,
           'content' => $faker->paragraph,
           'status' => 'published',
       ];
   });
   

5. Performance

   • Add indexes to frequently queried columns:

     Schema::table('articles', function (Blueprint $table) {
         $table->index('slug');
         $table->index('status');
     });
     

   • Use with() for eager loading:

     $articles = Article::with('categories')->get();
     

6. Custom Validation Extend the Article model for custom rules:

   public static function boot() {
       parent::boot();
       static::addGlobalScope('active', function (Builder $builder) {
           $builder->where('status', '!=', 'archived');
       });
   }
   

7. Asset Management Store article assets (images, PDFs) in a dedicated directory:

   $path = storage_path('app/articles/'.$article->id.'/image.jpg');