Agility Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require developtech/agility-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       DevelopTech\AgilityBundle\DevelopTechAgilityBundle::class => ['all' => true],
   ];
   

2. Database Migrations Run migrations to create tables for projects, sprints, user stories, tasks, and feedbacks:

   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

3. First Use Case Create a project via CLI:

   php bin/console agility:project:create --name="My Agile Project" --description="Project description"
   

   Access the admin dashboard at /agility/admin (ensure routing is configured).

Where to Look First

• Documentation: Check Resources/doc/ for bundle-specific docs (if available).
• Controllers: src/Controller/ for CRUD operations (e.g., ProjectController, SprintController).
• Entities: src/Entity/ for models like Project, UserStory, Task, etc.
• Twig Templates: Resources/views/ for UI components (e.g., sprint boards, backlogs).
• Fixtures: DataFixtures/ for sample data (if provided).

Implementation Patterns

Core Workflows

1. Project Management

   • Create/Update Projects: Use the ProjectManager service or CLI commands to scaffold projects.

     $project = $this->get('agility.project_manager')->create(
         'Project Name',
         'Description',
         ['team_member1@example.com', 'team_member2@example.com']
     );
     

   • Assign Teams: Use the Team entity to group users under projects.

2. Sprint Planning

   • Create Sprints:

     $sprint = $this->get('agility.sprint_manager')->create(
         $project,
         'Sprint 1',
         new \DateTime('2023-10-01'),
         new \DateTime('2023-10-15')
     );
     

   • Add User Stories: Drag-and-drop stories from the backlog to the sprint via the admin UI or API.

3. Task Tracking

   • Create Tasks:

     $task = $this->get('agility.task_manager')->create(
         $userStory,
         'Implement login API',
         'High'
     );
     

   • Update Status: Use the Task entity’s status field (e.g., TODO, IN_PROGRESS, DONE).

     $task->setStatus('IN_PROGRESS')->save();
     

4. Feedback Loops

   • Log Feedback:

     $feedback = $this->get('agility.feedback_manager')->create(
         $task,
         'Client feedback: Add CSRF protection',
         'High'
     );
     

Integration Tips

1. Custom Fields Extend entities with custom fields (e.g., Task):

   // src/Entity/Task.php
   /**
    * @ORM\Column(type="string", nullable=true)
    */
   private $customField;
   

   Update migrations and forms accordingly.

2. Event Listeners Hook into lifecycle events (e.g., sprint start/end):

   // src/EventListener/SprintListener.php
   class SprintListener implements EventSubscriberInterface {
       public static function getSubscribedEvents() {
           return [
               SprintEvents::SPRINT_START => 'onSprintStart',
           ];
       }
       public function onSprintStart(SprintEvent $event) {
           // Send notifications, etc.
       }
   }
   

3. API Endpoints Use Symfony’s serializers to expose data:

   # config/routes.yaml
   agility_api:
       resource: "@DevelopTechAgilityBundle/Resources/config/routing/api.yaml"
       prefix: /api/agility
   

   Customize serializers in src/Serializer/ if needed.

4. Authentication Secure routes with Symfony’s security component:

   # config/packages/security.yaml
   access_control:
       - { path: ^/agility, roles: ROLE_AGILITY_USER }
   

Gotchas and Tips

Pitfalls

1. Database Schema

   • Issue: Missing migrations after entity changes.
   • Fix: Always run doctrine:migrations:diff and migrate after modifying entities.
   • Tip: Use make:migration for complex changes.

2. Permissions

   • Issue: Unauthorized access to sprints/projects.
   • Fix: Implement Symfony’s voter system or ACLs:

     // src/Voter/ProjectVoter.php
     class ProjectVoter extends Voter {
         protected function supports(string $attribute, $subject) {
             return $attribute === 'EDIT' && $subject instanceof Project;
         }
         protected function voteOnAttribute(string $attribute, $subject, TokenInterface $token) {
             // Custom logic here
         }
     }
     

3. Performance

   • Issue: Slow sprint boards with many tasks.
   • Fix: Add indexes to frequently queried fields (e.g., task.status).
   • Tip: Use DQL or QueryBuilder for complex queries:

     $tasks = $entityManager->createQueryBuilder()
         ->select('t')
         ->from(Task::class, 't')
         ->where('t.sprint = :sprint')
         ->andWhere('t.status = :status')
         ->setParameter('sprint', $sprint)
         ->setParameter('status', 'TODO')
         ->getQuery()
         ->getResult();
     

4. UI Quirks

   • Issue: Twig templates not updating after changes.
   • Fix: Clear cache:

     php bin/console cache:clear
     

   • Tip: Use {{ dump() }} in Twig to debug variables.

Debugging Tips

1. Log Entities Enable Doctrine logging in config/packages/dev/doctrine.yaml:

   doctrine:
       dbal:
           logging: true
           profiling: true
   

2. Event Debugging Dump events in listeners:

   public function onSprintStart(SprintEvent $event) {
       \Log::debug('Sprint started:', ['sprint' => $event->getSprint()->getName()]);
   }
   

3. CLI Commands List available commands:

   php bin/console list agility
   

   Debug command arguments:

   php bin/console agility:sprint:create --help
   

Extension Points

1. Custom Entities Extend existing entities (e.g., Task) by overriding them in your app:

   // src/Entity/Task.php
   namespace App\Entity;
   use DevelopTech\AgilityBundle\Entity\Task as BaseTask;
   
   class Task extends BaseTask {
       // Add custom methods/fields
   }
   

   Update config/packages/doctrine.yaml to map the new entity:

   orm:
       entity_managers:
           default:
               mappings:
                   App:
                       is_bundle: false
                       dir: '%kernel.project_dir%/src/Entity'
                       prefix: 'App\Entity'
                       alias: App
   

2. Custom Services Override bundle services in config/services.yaml:

   services:
       DevelopTech\AgilityBundle\Manager\TaskManager:
           class: App\Service\CustomTaskManager
           arguments: ['@service_container']
   

3. Twig Extensions Add custom filters/functions:

   // src/Twig/AppExtension.php
   class AppExtension extends \Twig\Extension\AbstractExtension {
       public function getFilters() {
           return [
               new \Twig\TwigFilter('custom_task_status', [$this, 'formatTaskStatus']),
           ];
       }
       public function formatTaskStatus($status) {
           return str_replace('_', ' ', ucwords($status));
       }
   }
   

   Register in config/packages/twig.yaml:

   twig:
       globals:
           app_extension: '@app.twig_extension'
   

4. API Extensions Extend the API with custom controllers:

   // src/Controller/Agility/CustomTaskController.php
   class CustomTaskController extends AbstractController {
       #[Route('/api/agility/tasks/custom', name: 'agility_custom_task', methods: ['GET'])]
       public function customTaskList(TaskManager $taskManager) {
           return $this->json($taskManager->getCustomTasks());
       }
   }