Hidev Hiqdev Laravel Package

Getting Started

To leverage hiqdev/hidev-hiqdev in a Laravel project, follow these minimal steps:

1. Install the Package Add the package to your project via Composer:

   composer require hiqdev/hidev-hiqdev
   

2. Understand the Purpose This package provides pre-configured vendor settings for HiDev (HiQDev’s automation tool), including:

   • Vendor metadata (name, company title).
   • Contact details (email, GitHub, forum).
   • Author profiles (names, roles, emails, GitHub links).
   • Default BSD-3-Clause license configuration.

3. Locate Key Files The primary configuration resides in:

   • vendor/hiqdev/hidev-hiqdev/src/config/goals.yml (Defines HiQDev’s standardized settings for HiDev).

4. First Use Case: Standardizing Vendor Metadata If your Laravel project uses HiDev for scaffolding or needs consistent vendor configurations, copy the goals.yml to your project’s root (e.g., config/hidev/goals.yml) and customize it for your team’s needs.

Implementation Patterns

Workflow Integration

1. HiDev-Based Scaffolding

   • Use this package only if your team uses HiDev for code generation.
   • Example: Generate Laravel boilerplate via HiDev, then override goals.yml to include Laravel-specific metadata (e.g., laravel.com links, custom license files).

2. Composer Script Hooks Integrate the package’s configs into Laravel’s workflow via composer.json scripts:

   "scripts": {
       "post-install-cmd": [
           "php vendor/bin/hidev generate:config --config=vendor/hiqdev/hidev-hiqdev/src/config/goals.yml"
       ]
   }
   

3. Custom Configuration Overrides Extend or replace the default goals.yml to fit Laravel’s conventions:

   # Example: config/hidev/goals.yml
   vendor:
       name: "YourCompany"
       company: "YourCompany Inc."
       license: "MIT"  # Override BSD-3-Clause if needed
   authors:
       - name: "John Doe"
         email: "john@example.com"
         github: "https://github.com/johndoe"
         role: "Lead Developer"
   

4. PHPCS Integration Leverage HiQDev’s PHPCS rules (defined in the package) by adding a php-cs-fixer.dist.php to your project:

   <?php
   return (new PhpCsFixer\Config())
       ->setRules(require __DIR__.'/vendor/hiqdev/hidev-hiqdev/src/config/php-cs-fixer.php');
   

Laravel-Specific Adaptations

• Publish Configs Create a custom Artisan command to publish the goals.yml to a Laravel-friendly location:

  php artisan vendor:publish --provider="YourPackageServiceProvider" --tag="hidev-config"
  

  Then, update config/app.php to include the published config.

• License File Generation Use the package’s license template to generate a LICENSE.md for your Laravel project:

  php vendor/bin/hidev generate:license --output=LICENSE.md
  

Gotchas and Tips

Pitfalls

1. HiDev Dependency

   • This package requires HiDev to function. If your team doesn’t use HiDev, the package is useless for automation.
   • Workaround: Manually copy the goals.yml and PHPCS configs to your project.

2. Stale Maintenance

   • Last updated in 2017, with no recent activity. Risks:
     • Incompatibility with modern PHP-CS-Fixer or Composer versions.
     • Broken HiDev integration.
   • Mitigation: Fork the repo and update dependencies (e.g., php-cs-fixer, symfony/yaml).

3. Laravel Mismatch

   • The package is not Laravel-aware. Avoid:
     • Expecting Laravel-specific features (e.g., route generation, Blade stubs).
     • Direct integration with Laravel’s service container or facades.
   • Tip: Use it only for metadata/configuration, not core Laravel workflows.

4. PHPCS Configuration Quirks

   • The package’s PHPCS rules may conflict with Laravel’s default coding standards.
   • Debugging: Run PHPCS with --dry-run to identify issues:

     vendor/bin/php-cs-fixer fix --dry-run --rules=@hiqdev
     

5. License Conflicts

   • The default license is BSD-3-Clause, which may not align with Laravel’s MIT license.
   • Solution: Override the license field in goals.yml or manually edit the generated LICENSE.md.

Debugging Tips

• HiDev Command Issues If HiDev commands fail, ensure:

  • The hidev binary is installed globally or via Composer:

    composer global require hiqdev/hidev
    

  • The goals.yml path is correct (use absolute paths if needed).

• YAML Parsing Errors The package uses Symfony YAML 3.0. If your project uses an older version, update:

  composer require symfony/yaml:^3.0
  

• PHPCS Fixer Errors If PHPCS fails with "unsupported fixers," update the config in php-cs-fixer.php to match your installed version:

  return [
      'rules' => [
          '@HiQDev' => true,
          // Override unsupported fixers (e.g., 'empty_return')
          'empty_return' => false,
      ],
  ];
  

Extension Points

1. Custom Templates Extend the package by creating a custom HiDev plugin that inherits from hidev-hiqdev:

   # config/hidev/plugins.yml
   plugins:
       - hiqdev/hidev-hiqdev
       - yourcompany/hidev-laravel
   

2. Dynamic Config Loading Load the goals.yml dynamically in a Laravel service provider:

   public function boot()
   {
       $config = Yaml::parse(file_get_contents(__DIR__.'/../../vendor/hiqdev/hidev-hiqdev/src/config/goals.yml'));
       $this->app['config']->set('hidev', $config);
   }
   

3. CI/CD Integration Use the package’s configs in GitHub Actions or Travis CI:

   # .github/workflows/ci.yml
   jobs:
       phpcs:
           runs-on: ubuntu-latest
           steps:
               - uses: actions/checkout@v2
               - run: vendor/bin/php-cs-fixer fix --rules=@hiqdev