Git Helper Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require darkikim/git-helper
   

   Ensure your composer.json includes the package under require (not require-dev unless explicitly needed for CI/dev).

2. Enable the Bundle Add to config/bundles.php (Symfony 5.2+):

   return [
       // ...
       Kikim\GitHelper\GitHelperBundle::class => ['dev' => true],
       // ...
   ];
   

   Note: Set dev: true to avoid cluttering production toolbars.

3. First Use Case Visit any route in your dev environment. The Symfony Toolbar will now display:

   • Last Commit SHA (e.g., abc1234)
   • Author Name (e.g., johndoe)
   • Commit Message (truncated if long)
   • Timestamp (relative, e.g., "2 hours ago")
   • Branch Name (e.g., feature/login).

   Verify: Check the "Git" tab in the Toolbar (or the default "GitHelper" section if not customized).

Implementation Patterns

Workflows

1. Local Development

   • Use the Toolbar to quickly identify the latest commit context (e.g., debugging a regression introduced in abc1234).
   • Pro Tip: Combine with git blame for line-level context:

     git blame app/Http/Controllers/UserController.php
     

     Then cross-reference the SHA in the Toolbar.

2. CI/CD Integration

   • Disable the bundle in production (dev: false in bundles.php).
   • For CI pipelines, use the package’s underlying logic via its service to fetch Git metadata programmatically:

     use Kikim\GitHelper\GitHelper;
     $gitHelper = $this->container->get(GitHelper::class);
     $lastCommit = $gitHelper->getLastCommit();
     // Log or use $lastCommit['sha'], $lastCommit['message'], etc.
     

3. Customizing Toolbar Display Override the Twig template to modify the output:

   • Copy vendor/kikim/git-helper/src/Resources/views/GitHelper/toolbar.html.twig to templates/bundles/GitHelper/toolbar.html.twig.
   • Extend with additional Git data (e.g., commit distance from main):

     {% extends 'GitHelper/toolbar.html.twig' %}
     {% block git_helper_content %}
         {{ parent() }}
         <div class="git-helper-distance">
             Ahead: {{ gitHelper.getCommitDistance('main') }} commits
         </div>
     {% endblock %}
     

4. Command-Line Access Use the bundle’s service in console commands:

   use Kikim\GitHelper\GitHelper;
   use Symfony\Component\Console\Command\Command;
   use Symfony\Component\Console\Input\InputInterface;
   use Symfony\Component\Console\Output\OutputInterface;
   
   class GitInfoCommand extends Command {
       protected static $defaultName = 'app:git-info';
       private GitHelper $gitHelper;
   
       public function __construct(GitHelper $gitHelper) {
           $this->gitHelper = $gitHelper;
           parent::__construct();
       }
   
       protected function execute(InputInterface $input, OutputInterface $output): int {
           $commit = $this->gitHelper->getLastCommit();
           $output->writeln(sprintf(
               'Last commit: %s by %s - %s',
               $commit['sha'],
               $commit['author'],
               $commit['message']
           ));
           return Command::SUCCESS;
       }
   }
   

Gotchas and Tips

Pitfalls

1. Git Repository Not Detected

   • Issue: Toolbar shows no Git data if the project root isn’t a Git repo or the .git directory is inaccessible.
   • Fix: Ensure the bundle runs in a Git repo. Debug with:

     $this->container->get('kikim_git_helper.git_helper')->isGitRepo();
     

     Return false if outside a repo.

2. Performance Overhead

   • Issue: Frequent Git calls (e.g., in a loop) may slow down requests.
   • Fix: Cache the GitHelper service or limit usage to CLI/commands:

     # config/services.yaml
     Kikim\GitHelper\GitHelper:
         public: false
     

3. Symfony Cache Conflicts

   • Issue: Toolbar data may stale if Symfony’s cache is aggressive.
   • Fix: Exclude GitHelper from cache warming or use cache:clear --no-warmup.

4. Multi-Repo Projects

   • Issue: The bundle defaults to the root repo. Submodules or nested repos may cause confusion.
   • Fix: Manually set the repo path:

     $gitHelper->setRepoPath(__DIR__ . '/../submodule-repo');
     

Debugging

• Log Git Data Enable debug mode in config/packages/dev/kikim_git_helper.yaml:

  kikim_git_helper:
      debug: true
  

  Logs will appear in var/log/dev.log.

• Check GitHelper Service Dump the service’s raw data:

  dd($this->container->get('kikim_git_helper.git_helper')->getLastCommit());
  

Extension Points

1. Add Custom Git Commands Extend the bundle’s GitHelper service to support additional Git commands (e.g., getBranches()):

   use Kikim\GitHelper\GitHelper;
   class CustomGitHelper extends GitHelper {
       public function getBranches(): array {
           exec('git branch --format "%(refname:short)"', $branches);
           return array_filter($branches);
       }
   }
   

   Override the service in config/services.yaml:

   Kikim\GitHelper\GitHelper: '@custom_git_helper'
   

2. Localization Translate commit messages or timestamps:

   {{ gitHelper.lastCommit.message|trans }}
   {{ gitHelper.lastCommit.timestamp|date('d/m/Y H:i') }}
   

3. Security

   • Sensitive Data: Avoid exposing commit messages with secrets (e.g., API keys) in the Toolbar. Use .gitignore or pre-commit hooks to sanitize messages.
   • File Access: Restrict the bundle to trusted environments (e.g., via APP_ENV checks in a custom service).

4. Testing Mock the GitHelper service in PHPUnit:

   $this->container->set('kikim_git_helper.git_helper', $this->createMock(GitHelper::class));
   $mockGitHelper->method('getLastCommit')->willReturn([
       'sha' => 'test123',
       'author' => 'testuser',
       'message' => 'Test commit',
   ]);