Social Rest Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require antwebes/social-rest-bundle
   

   Enable the bundle in app/AppKernel.php:

   new Ant\SocialRestBundle\AntSocialRestBundle(),
   

2. Configuration: Ensure FOSRestBundle is installed (required for error handling and API responses). Configure error codes in app/config/codes.yml:

   profile:
       user:
           exist:
               message: "User already exists."
               code: 409
   

3. First Use Case: Trigger a profile visit via API:

   POST /api/users/{user_id}/visits
   

   Or for authenticated users:

   POST /api/users/{id}/profiles/visits
   

Implementation Patterns

Core Workflows

1. Profile Management:

   • Extend Ant\SocialRestBundle\Controller\ProfileController for custom profile logic.
   • Use events (AntSocialRestEvents) to hook into lifecycle methods (e.g., PROFILE_SHOW_COMPLETED).

2. Event-Driven Extensions:

   • Subscribe to events in a service listener (e.g., ProfileResponseEvent):

     // src/Acme/UserBundle/Listener/ProfileListener.php
     class ProfileListener implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 AntSocialRestEvents::PROFILE_SHOW_COMPLETED => 'onProfileShowCompleted',
             ];
         }
         public function onProfileShowCompleted(ProfileResponseEvent $event) {
             $event->getResponse()->headers->set('X-Custom-Header', 'value');
         }
     }
     

   • Register the listener in services.yml:

     services:
         acme.profile_listener:
             class: Acme\UserBundle\Listener\ProfileListener
             tags:
                 - { name: kernel.event_subscriber }
     

3. Error Handling:

   • Use serviceError() in controllers to return standardized errors:

     return $this->serviceError('profile.user.exist', 409);
     

   • Ensure api.servicio.code_loader is configured to load codes.yml.

4. Profile Visits:

   • Track visits via /api/users/{id}/visits (increment counter).
   • Differentiate between authenticated (POST /api/users/{id}/profiles/visits) and anonymous visits.

Integration Tips

• Symfony Forms: Leverage built-in form handling in controllers (e.g., ProfileController::editAction).
• Caching: Use COMPLETED events to modify responses (e.g., add cache headers):

  $event->getResponse()->setSharedMaxAge(3600); // Cache for 1 hour
  

• API Routes: Extend routing in routing.yml:

  acme_profile:
      resource: "@AntSocialRestBundle/Resources/config/routing.yml"
      prefix: /api
  

Gotchas and Tips

Pitfalls

1. Event Naming:

   • Events are case-sensitive (e.g., PROFILE_SHOW_COMPLETED vs profile_show_completed).
   • Verify events in AntSocialRestEvents class before subscribing.

2. Error Codes:

   • Missing codes.yml entries will throw UndefinedIndexException.
   • Ensure HTTP status codes (e.g., 409) match Symfony’s valid statuses.

3. Deprecated Features:

   • Avoid using visitDate as a primary key (deprecated in v0.1.1; use id instead).

4. FOSRestBundle Dependency:

   • Without FOSRestBundle, error responses (e.g., ErrorResponse::createResponse) will fail.

Debugging

• Event Dispatching:
  • Use debug:event-dispatcher to list active events:

    php bin/console debug:event-dispatcher
    

• Listener Debugging:
  • Log event payloads in listeners:

    public function onProfileShowCompleted(ProfileResponseEvent $event) {
        error_log(print_r($event->getResponse()->getContent(), true));
    }
    

Extension Points

1. Custom Entities:

   • Override the Visit entity (e.g., app/Resources/AntSocialRestBundle/Entity/Visit.php) to add fields like ip_address:

     /**
      * @ORM\Column(type="string", length=45)
      */
     private $ipAddress;
     

2. Dynamic Redirects:

   • Modify COMPLETED events to change redirects:

     public function onProfileUpdateCompleted(ProfileResponseEvent $event) {
         $event->setResponse(new RedirectResponse('/custom-path'));
     }
     

3. Validation:

   • Extend form validation in INITIALIZE events:

     public function onProfileInitialize(ProfileEvent $event) {
         $event->getForm()->add('custom_field', 'text', [
             'constraints' => [new NotBlank()]
         ]);
     }
     

4. Performance:

   • Cache codes.yml loading in code_loader service for high-traffic APIs:

     services:
         api.servicio.code_loader:
             class: Ant\SocialRestBundle\Service\CodeLoader
             calls:
                 - [setCache, ['%kernel.cache_dir%/codes_cache']]