Jsend Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require artprima/jsend-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Artprima\JsendBundle\ArtprimaJsendBundle::class => ['all' => true],
   ];
   

2. First Use Case Inject the JsendResponse service into a controller and use it to wrap API responses:

   use Artprima\JsendBundle\Response\JsendResponse;
   
   class ApiController extends AbstractController
   {
       public function successResponse(JsendResponse $jsend): Response
       {
           return $jsend->success(['message' => 'Operation completed']);
       }
   
       public function errorResponse(JsendBundle $jsend): Response
       {
           return $jsend->fail('Something went wrong');
       }
   }
   

3. Where to Look First

   • Bundle Configuration: Check config/packages/artprima_jsend.yaml (if auto-generated).
   • Response Class: Review src/Response/JsendResponse.php for available methods (success, fail, error).
   • Twig Integration: If using Twig, verify src/Twig/JsendExtension.php for template helpers.

Implementation Patterns

Core Workflows

1. API Response Standardization Replace raw JsonResponse with JsendResponse for consistent JSend-compliant payloads:

   // Before
   return new JsonResponse(['status' => 'success', 'data' => $data]);
   
   // After
   return $jsend->success($data);
   

2. Error Handling Use fail() for client errors (e.g., validation) and error() for server errors:

   try {
       $result = $service->execute();
       return $jsend->success($result);
   } catch (ValidationException $e) {
       return $jsend->fail($e->getMessage());
   } catch (\Exception $e) {
       return $jsend->error($e->getMessage());
   }
   

3. Middleware Integration Wrap middleware responses for uniformity:

   public function handle(Request $request, Closure $next): Response
   {
       try {
           return $next($request);
       } catch (UnauthorizedHttpException $e) {
           return $jsend->fail('Unauthorized', 401);
       }
   }
   

4. Twig Integration (if enabled) Use Twig helpers to render JSend-compliant JSON in templates:

   {{ dump(jsend_success({'message': 'Hello'})) }}
   

Integration Tips

• Symfony Messenger: Return JsendResponse from message handlers for async workflows.
• API Platform: Override JsonLdSerializer to use JsendResponse for consistent serialization.
• Doctrine Events: Return JsendResponse from event listeners for API consistency.

Gotchas and Tips

Pitfalls

1. No Auto-Configuration Unlike popular bundles, this lacks auto-configuration. Manually register the bundle in bundles.php and verify services are loaded.

2. Deprecated Symfony Versions The composer.json requires PHP 5.3.3 and Symfony 2.x components (e.g., sensio/framework-extra-bundle). Ensure compatibility with your stack.

3. Missing Documentation No formal docs exist. Reverse-engineer usage from:

   • src/Response/JsendResponse.php (core methods).
   • tests/ (if available) for edge cases.

4. Twig Extension Not Auto-Enabled If using Twig, manually enable the extension in config/packages/twig.yaml:

   twig:
       extensions:
           - Artprima\JsendBundle\Twig\JsendExtension
   

Debugging

• Service Not Found? Clear cache and verify the bundle is registered:

  php bin/console cache:clear
  php bin/console debug:container jsend
  

• JSON Output Mismatch Check if the response is being double-serialized (e.g., by a global listener). Use dd($jsend->getData()) to inspect raw payloads.

Extension Points

1. Custom Response Types Extend JsendResponse to add domain-specific statuses:

   class CustomJsendResponse extends JsendResponse
   {
       public function warning($message, $data = []): Response
       {
           return $this->createResponse('warning', $message, $data);
       }
   }
   

2. Override Serialization Modify the serialize() method in JsendResponse to customize the JSON structure (e.g., add metadata).

3. Event Listeners Attach listeners to kernel.response to post-process JsendResponse objects (e.g., add logging or headers):

   public function onKernelResponse(FilterResponseEvent $event): void
   {
       $response = $event->getResponse();
       if ($response instanceof JsendResponse) {
           $response->headers->set('X-JSend', 'true');
       }
   }
   

Configuration Quirks

• No Config File The bundle doesn’t generate a default artprima_jsend.yaml. Override behavior via DI:

  services:
      Artprima\JsendBundle\Response\JsendResponse:
          arguments:
              $defaultStatus: 'success' # Override default status