Article Post Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require baks-dev/article-post
   php bin/console baks:assets:install
   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

   • Verify baks-dev/core (v7.4+) is installed as a dependency.

2. First Use Case

   • Access the article CRUD interface via /admin/articles (if using BaksDev’s admin panel).
   • Create a test article using the ArticlePost entity:

     use BaksDev\ArticlePost\Entity\ArticlePost;
     
     $article = new ArticlePost();
     $article->setTitle('Test Article');
     $article->setSlug('test-article');
     $article->setContent('Hello, world!');
     $entityManager->persist($article);
     $entityManager->flush();
     

3. Where to Look First

   • Entities: src/Entity/ArticlePost.php (core model).
   • Controllers: src/Controller/ (if included; check for REST/CRUD endpoints).
   • Templates: Look for Twig templates in templates/article_post/ (if using Symfony).
   • Configuration: config/packages/baks_article_post.yaml (if auto-generated by baks:assets:install).

Implementation Patterns

Core Workflows

1. Article Management

   • Create/Update: Use the ArticlePost entity with setters (setTitle(), setSlug(), setContent()). Example with validation:

     use Symfony\Component\Validator\Constraints as Assert;
     
     $article = new ArticlePost();
     $article->setTitle('My Post');
     $article->setSlug('my-post'); // Auto-generate via `generateSlug()` if available
     $article->setContent('Content...');
     $article->setStatus(ArticlePost::STATUS_DRAFT); // Use constants from entity
     

   • Publish/Unpublish:

     $article->setStatus(ArticlePost::STATUS_PUBLISHED);
     $entityManager->flush();
     

2. Slug Handling

   • If the package supports auto-slugging, use:

     $article->setTitle('New Post Title');
     $article->generateSlug(); // Hypothetical method; check entity
     

   • Override slug generation in a service if needed.

3. Relationships

   • Categories/Tags (if supported):

     $category = $entityManager->getRepository(Category::class)->find(1);
     $article->addCategory($category);
     

   • Media/Attachments: Use ArticlePostAttachment entity (if exists) to link files/images.

4. API Integration

   • Expose endpoints via Symfony’s AbstractController:

     use BaksDev\ArticlePost\Controller\ArticlePostController;
     
     // Extend or override default controller logic.
     

5. Event Listeners

   • Listen for article_post.pre_persist or article_post.post_update events (if documented):

     // config/services.yaml
     BaksDev\ArticlePost\EventListener\MyListener:
         tags:
             - { name: kernel.event_listener, event: article_post.pre_persist, method: onPrePersist }
     

Integration Tips

• Custom Fields: Extend the ArticlePost entity or use Doctrine extensions for extra fields (e.g., json columns for metadata).

  /**
   * @ORM\Column(type="json")
   */
  private $metadata = [];
  

• Search: Use Symfony’s Elasticsearch or Doctrine\ORM queries:

  $articles = $entityManager->createQuery(
      'SELECT a FROM BaksDevArticlePostBundle:ArticlePost a WHERE a.title LIKE :query'
  )->setParameter('query', '%search%')->getResult();
  

• Admin Panel: If using BaksDev’s admin bundle, configure permissions in security.yaml:

  access_control:
      - { path: ^/admin/articles, roles: ROLE_ADMIN }
  

Gotchas and Tips

Pitfalls

1. Missing Dependencies

   • Ensure baks-dev/core (v7.4+) is installed. Conflicts may arise with older versions.
   • Fix: Run composer update baks-dev/core if issues persist.

2. Slug Collisions

   • Auto-generated slugs may conflict. Override the generateSlug() method or use a unique suffix:

     $article->setSlug('unique-' . uniqid() . '-slug');
     

3. Migration Issues

   • If doctrine:migrations:diff fails, check for:
     • Missing baks-dev/core migrations.
     • Custom entity extensions not accounted for.
   • Fix: Manually create a migration or run php bin/console doctrine:schema:update --force.

4. Undocumented Features

   • The package lacks stars/documentation, so:
     • Inspect src/ for undocumented classes (e.g., ArticlePostAttachment).
     • Check for EventDispatcher usage in Entity/ArticlePost.php.

5. PHP 8.4+ Requirements

   • Avoid deprecated functions (e.g., create_function()). Use modern alternatives if extending.

Debugging

• Entity Not Found: Verify the entity namespace (BaksDev\ArticlePost\Entity\ArticlePost) matches your use statements.

  php bin/console debug:autowiring BaksDev\ArticlePost
  

• Validation Errors: Enable Symfony’s validator debug mode:

  php bin/console debug:validator
  

• Console Command Issues: Clear cache after installing assets:

  php bin/console cache:clear
  

Extension Points

1. Custom Repositories Extend ArticlePostRepository for complex queries:

   namespace App\Repository;
   
   use BaksDev\ArticlePost\Repository\ArticlePostRepository as BaseRepository;
   
   class ArticlePostRepository extends BaseRepository {
       public function findPublishedWithCategory(int $categoryId) {
           return $this->createQueryBuilder('a')
               ->where('a.status = :status')
               ->andWhere('a.category = :category')
               ->setParameter('status', ArticlePost::STATUS_PUBLISHED)
               ->setParameter('category', $categoryId)
               ->getQuery()
               ->getResult();
       }
   }
   

   Register in services.yaml:

   App\Repository\ArticlePostRepository:
       decorates: 'baks_dev.article_post.repository.article_post'
       arguments: ['@App\Repository\ArticlePostRepository.inner']
   

2. Twig Extensions Add custom filters/global variables:

   // src/Twig/AppExtension.php
   namespace App\Twig;
   
   use BaksDev\ArticlePost\Entity\ArticlePost;
   use Twig\Extension\AbstractExtension;
   use Twig\TwigFunction;
   
   class AppExtension extends AbstractExtension {
       public function getFunctions() {
           return [
               new TwigFunction('format_article_excerpt', [$this, 'formatExcerpt']),
           ];
       }
   
       public function formatExcerpt(ArticlePost $article, int $length = 100) {
           return Str::limit(strip_tags($article->getContent()), $length);
       }
   }
   

3. Form Types Override the default form type (if provided):

   // src/Form/ArticlePostType.php
   namespace App\Form;
   
   use BaksDev\ArticlePost\Form\ArticlePostType as BaseType;
   use Symfony\Component\Form\AbstractType;
   use Symfony\Component\Form\FormBuilderInterface;
   
   class ArticlePostType extends BaseType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           parent::buildForm($builder, $options);
           $builder->add('customField', TextType::class);
       }
   }
   

   Update services.yaml to replace the original:

   App\Form\ArticlePostType:
       tags: [form.type, { name: baks_dev_article_post_type }]
   

Configuration Quirks

• Asset Installation: Running baks:assets:install may overwrite existing configs. Backup config/packages/ before running.
• Environment Variables: Check for undocumented .env keys (e.g., BAKS_ARTICLE_POST_DEFAULT_CATEGORY). Add to .env if needed:

  BAKS_ARTICLE_POST_DEFAULT_CATEGORY=1
  

• Caching: Clear cache after extending entities or forms:

  php bin/console cache:pool:clear cache.app