Ijasahsmabundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle via Composer in a Symfony 2.7 project:

   composer require ais/ijasahsmabundle
   

   Register the bundle in app/AppKernel.php:

   new Ais\IjasahSmaBundle\AisIjasahSmaBundle(),
   

2. First Use Case The bundle appears to provide IjasahSma functionality (likely related to Ijasah/SMA, a system for managing academic certificates or diplomas in Indonesia). Start by exploring:

   • Doctrine Entities: Check src/Ais/IjasahSmaBundle/Entity/ for models like Certificate, Student, or Institution.
   • Controllers: Look for RESTful endpoints in src/Ais/IjasahSmaBundle/Controller/ (e.g., CertificateController).
   • Configuration: Review Resources/config/routing.yml for API routes (e.g., /api/certificates).

3. Quick Test Run the built-in API docs (if nelmio_api_doc is configured) at /app_dev.php/doc to inspect endpoints.

Implementation Patterns

Core Workflows

1. Certificate Management

   • CRUD Operations: Use the friendsofsymfony/rest-bundle endpoints (e.g., POST /api/certificates to issue a new certificate).
   • Validation: Leverage jms/serializer-bundle for input/output formatting (check Serializer configurations in Resources/config/serializer/).
   • Example:

     // In a controller
     $certificate = new Certificate();
     $certificate->setStudent($studentEntity);
     $certificate->setInstitution($institutionEntity);
     $certificate->setIssuedAt(new \DateTime());
     $em->persist($certificate);
     $em->flush();
     

2. Student/Institution Integration

   • Use Doctrine relationships (e.g., OneToMany between Student and Certificate) to fetch associated data:

     $student = $em->getRepository(Student::class)->find($id);
     $certificates = $student->getCertificates(); // Assuming getter exists
     

3. API-Driven Frontend

   • Consume endpoints with guzzle (dev dependency) for frontend integration:

     $client = new \GuzzleHttp\Client();
     $response = $client->post('/api/certificates', [
         'json' => ['student_id' => 123, 'institution_id' => 456]
     ]);
     

4. Asset Processing

   • Use leafo/scssphp and patchwork/jsqueeze for certificate PDF/HTML generation (check Twig templates in Resources/views/).

Integration Tips

• Symfony Forms: Extend CertificateType (if available) for form handling:

  $builder->add('student', EntityType::class, ['class' => Student::class]);
  

• Event Listeners: Hook into CertificateEvents (if defined) for workflows like email notifications (via swiftmailer):

  $dispatcher->addListener(CertificateEvents::POST_CREATE, function ($event) {
      $this->mailer->send(new CertificateIssuedEmail($event->getCertificate()));
  });
  

• Testing: Use liip/functional-test-bundle to test API endpoints:

  $client->request('GET', '/api/certificates/1');
  $this->assertEquals(200, $client->getResponse()->getStatusCode());
  

Gotchas and Tips

Pitfalls

1. Deprecated Symfony Version

   • The bundle targets Symfony 2.7, which is end-of-life. Migrate to Symfony 4/5+ or fork the bundle for compatibility.
   • Workaround: Use a compatibility layer like symfony/symfony v3.4 for partial upgrades.

2. Unstable Dependencies

   • Dev dependencies (@dev versions of rest-bundle, nelmio_api_doc) may break. Pin versions in composer.json:

     "friendsofsymfony/rest-bundle": "2.7.*",
     "nelmio/api-doc-bundle": "2.13.*"
     

3. Missing Documentation

   • No clear docs exist. Reverse-engineer from:
     • Entity annotations (e.g., @ORM\Table).
     • Controller actions (e.g., @Route paths).
     • Resources/config/doctrine/ for DQL queries.

4. Hardcoded Configs

   • Check for magic strings in Resources/config/config.yml (e.g., ijasah_sma.certificate_template). Override via:

     # config/packages/ais_ijasah_sma.yaml
     ais_ijasah_sma:
         certificate_template: 'custom/path/to/template.html.twig'
     

Debugging Tips

1. Doctrine Queries Enable SQL logging in .env:

   APP_DEBUG=1
   DATABASE_URL="mysql://user:pass@localhost/db?serverVersion=5.7&charset=utf8mb4&enable_utf8mb4=yes"
   

   Use dd() or var_dump() in controllers to inspect entities.

2. API Debugging

   • Check monolog logs for errors (configured via monolog-bundle).
   • Use Postman or curl to test endpoints:

     curl -X POST http://localhost/app_dev.php/api/certificates -H "Content-Type: application/json" -d '{"student_id":1}'
     

3. Asset Compilation

   • Clear Assetic cache if CSS/JS assets fail:

     php bin/console assetic:dump --env=dev
     

Extension Points

1. Custom Entities Extend existing entities (e.g., Certificate) by adding fields:

   /**
    * @ORM\Column(type="string", nullable=true)
    */
   private $customField;
   

   Update migrations and forms accordingly.

2. New Endpoints Add routes in Resources/config/routing.yml:

   api_certificate_verify:
       path: /api/certificates/{id}/verify
       defaults: { _controller: "AisIjasahSmaBundle:Certificate:verify" }
   

   Implement the controller action.

3. Event Subscribers Create a subscriber to extend workflows:

   class CertificateSubscriber implements EventSubscriber
   {
       public static function getSubscribedEvents()
       {
           return [CertificateEvents::PRE_PERSIST => 'onPrePersist'];
       }
   
       public function onPrePersist(LifecycleEventArgs $args)
       {
           $certificate = $args->getObject();
           $certificate->setIssuedAt(new \DateTime());
       }
   }
   

   Register in services.yml:

   services:
       ais_ijasah_sma.certificate_subscriber:
           class: AppBundle\EventListener\CertificateSubscriber
           tags:
               - { name: doctrine.event_subscriber }
   

4. Twig Extensions Add custom filters/functions in Resources/config/services.yml:

   services:
       ais_ijasah_sma.twig.extension:
           class: AppBundle\Twig\IjasahExtension
           tags:
               - { name: twig.extension }