Gitelephant Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require cypresslab/gitelephant-bundle:dev-master
   

   Register the bundle in AppKernel.php (only in dev/test environments):

   if (in_array($this->getEnvironment(), ['dev', 'test'])) {
       $bundles[] = new Cypress\GitElephantBundle\CypressGitElephantBundle();
   }
   

2. First Use Case: Inject the GitElephant service in a controller or command:

   use Cypress\GitElephantBundle\Service\GitElephant;
   
   class GitController extends Controller
   {
       public function __construct(GitElephant $gitElephant)
       {
           $this->gitElephant = $gitElephant;
       }
   
       public function showRepoStatus()
       {
           $status = $this->gitElephant->status();
           return $this->render('git/status.html.twig', ['status' => $status]);
       }
   }
   

3. Where to Look First:

   • Bundle docs: GitElephantBundle
   • Underlying library: GitElephant
   • Symfony services.yml for configuration (if any).

Implementation Patterns

Core Workflows

1. Repository Operations: Use the service to interact with Git repositories directly from Symfony:

   $this->gitElephant->pull();       // Pull latest changes
   $this->gitElephant->commit('msg'); // Commit changes
   $this->gitElephant->push();       // Push to remote
   

2. Command-Line Integration: Wrap GitElephant in a Symfony command for CLI tasks:

   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class GitPullCommand extends Command
   {
       protected function execute(InputInterface $input, OutputInterface $output)
       {
           $this->gitElephant->pull();
           $output->writeln('Repository pulled successfully.');
       }
   }
   

3. Event-Driven Hooks: Trigger actions on Git events (e.g., post-commit hooks) via Symfony events:

   // In a service or event subscriber
   $this->gitElephant->addPostCommitListener(function() {
       // Notify Slack/email/etc.
   });
   

4. Dependency Injection: Prefer constructor injection for testability:

   class GitService
   {
       public function __construct(private GitElephant $gitElephant) {}
   }
   

Integration Tips

• Environment Isolation: Restrict the bundle to dev/test environments to avoid exposing Git operations in production.
• Configuration: Override default paths (e.g., repo root) via services.yml:

  cypress_git_elephant:
      repo_path: '%kernel.project_dir%/../custom-repo'
  

• Error Handling: Wrap GitElephant calls in try-catch blocks for graceful failures:

  try {
      $this->gitElephant->push();
  } catch (\RuntimeException $e) {
      $this->addFlash('error', 'Git push failed: ' . $e->getMessage());
  }
  

Gotchas and Tips

Pitfalls

1. Environment Mismatch:

   • Issue: Forgetting to restrict the bundle to dev/test environments may expose sensitive Git operations in production.
   • Fix: Always wrap the bundle registration in in_array($this->getEnvironment(), ['dev', 'test']).

2. Path Assumptions:

   • Issue: GitElephant defaults to the current working directory. If your repo is elsewhere, operations will fail silently.
   • Fix: Explicitly set repo_path in services.yml or pass it to the service constructor.

3. Outdated Dependencies:

   • Issue: The bundle hasn’t been updated since 2020 and relies on Symfony 2.x. Compatibility with newer Symfony versions (5.x/6.x) is untested.
   • Fix: Test thoroughly in your environment or fork the bundle for updates.

4. Permission Errors:

   • Issue: Git operations may fail due to file permissions (e.g., .git directory inaccessible).
   • Fix: Ensure the Symfony process has read/write access to the repo:

     chmod -R 755 /path/to/repo
     

Debugging

• Verbose Output: Enable GitElephant’s debug mode via configuration:

  cypress_git_elephant:
      debug: true
  

  This logs raw Git commands executed.

• Command Inspection: Use strace or git --trace to debug low-level Git interactions:

  GIT_TRACE=1 git status  # Check raw Git output
  

Extension Points

1. Custom Git Commands: Extend the bundle by adding new methods to the GitElephant service:

   // In a custom service
   $this->gitElephant->customCommand('git custom-subcommand --args');
   

2. Event Listeners: Subscribe to Git events (e.g., pre-push) via Symfony’s event dispatcher:

   $dispatcher->addListener('git.pre_push', function() {
       // Validate commit messages, etc.
   });
   

3. Repository Abstraction: Create a decorator service to wrap GitElephant and add domain-specific logic:

   class CustomGitService
   {
       public function __construct(private GitElephant $gitElephant) {}
   
       public function safePush()
       {
           if ($this->hasUnstagedChanges()) {
               throw new \RuntimeException('Unstaged changes detected!');
           }
           $this->gitElephant->push();
       }
   }
   

Configuration Quirks

• Service Aliases: The bundle may not expose all GitElephant methods directly. Check the underlying service definition for available methods:

  # services.yml
  cypress_git_elephant:
      class: Cypress\GitElephantBundle\Service\GitElephant
      arguments: ['%kernel.root_dir%']
  

• Legacy Symfony: If using Symfony 3.x/4.x+, some bundle features (e.g., AppKernel) may require polyfills or adjustments. Test thoroughly.