Cli Options Parser Laravel Package

Product Decisions This Supports

• CLI Tooling & Developer Experience: Enables rapid development of command-line interfaces (CLIs) for internal tools, admin scripts, or public-facing CLI applications (e.g., php artisan-style workflows). Reduces boilerplate for parsing --flag, --option, and positional arguments.
• Roadmap for CLI-First Products: Justifies investment in CLI-driven features (data migration tools, batch processing, devops integrations) by providing a lightweight, maintainable parser. v2.0.0 does not add new parsing capabilities — it is a maintenance/hygiene release — so roadmap scope is unchanged; only the platform floor moved.
• Platform Baseline Decision (new in v2.0.0): The minimum PHP version is now 8.0+. This is a breaking change that ties adoption to your PHP upgrade roadmap. It becomes a forcing function: any decision to adopt this package is also a decision that the consuming app is on PHP 8.0+. For teams already on a modern runtime (Laravel 9+/10+ also require PHP 8.0+), this is a non-event; for teams running PHP 7.x (common in older Phalcon deployments), it is a blocker or an explicit upgrade project.
• Build vs. Buy: Still favors buy (adopt) over hand-rolled getopt() parsing. v2.0.0 strengthens the case: GitHub Actions CI, Codacy static analysis, and README badges are maintenance-health signals — evidence the package is actively stewarded rather than abandoned, which lowers the long-term support risk of a small dependency.
• Use Cases:
  • Internal scripts (e.g., php vendor/bin/your-tool --env=prod --limit=100).
  • Phalcon-based devops tools (database seeding, cron jobs).
  • Legacy system modernization where CLI access improves usability — subject to the PHP 8.0 floor.
  • Plugin systems where CLI options extend functionality (e.g., --plugin=analytics).

When to Consider This Package

• Adopt if:
  • Your application is on PHP 8.0 or newer (hard requirement as of v2.0.0) and your Phalcon version is compatible with that runtime.
  • Your app needs CLI support but lacks a dedicated parser.
  • You prioritize lightweight dependencies (BSD-3 license, no heavy frameworks, zero dependencies beyond Phalcon).
  • Your team is already using Phalcon and wants consistency in tooling.
  • You value maintenance signals: v2.0.0 adds GitHub Actions CI and Codacy analysis, so regressions are more likely to be caught upstream.
  • You need basic-to-intermediate argument parsing (flags, options, positional args) without complex validation.
• Look elsewhere if:
  • You are on PHP 7.x. v2.0.0 dropped support; you must either upgrade PHP first or pin to the 1.x line (with the understanding that 1.x is now off the maintained path — no CI/Codacy coverage from this release forward). Treat pinning as a tracked technical-debt item with an owner and a target upgrade date, not a permanent state.
  • You need advanced CLI features (argument validation, help generators, command autocompletion) → consider symfony/console or league/option. Note that this release adds no features here, so this gap is unchanged.
  • Your project is not Phalcon-based (this package is Phalcon-specific; the PHP 8.0 floor alone does not make it a general-purpose Laravel CLI parser).
  • You require cross-language CLI tools (e.g., Python/Ruby integrations).
  • Your team lacks PHP/Phalcon expertise.
• Adoption hygiene: pin the major version explicitly (^2.0), review the PHP 8.0 floor against your deployment matrix (staging, CI images, production hosts) before upgrading, and check your CI matrix enforces PHP 8.0+ so the constraint fails loudly rather than in production.

How to Pitch It (Stakeholders)

For Executives: "This package lets us build reliable CLI tools for [specific use case, e.g., 'automating database backups' or 'enabling devops teams to run Phalcon jobs without GUI access'] with minimal code — a lightweight, Phalcon-native solution under a BSD license, so no vendor lock-in. The new v2.0.0 release is a maintenance release, not a feature release: it adds continuous integration (GitHub Actions), automated code-quality analysis (Codacy), and modernises the codebase. That matters for risk — it's evidence the dependency is actively maintained, which is exactly what we want from something sitting in our tooling path. The one decision it forces is a platform floor: it now requires PHP 8.0+. If we're already on PHP 8, this is a low-risk, low-effort adoption we can prototype in a week. If any target environment is still on PHP 7, that's a small, scoped upgrade project we should schedule rather than absorb silently. No new functionality is being sold here — we're buying a tidier, better-instrumented version of the same tool."

For Engineering: *"Phalcon/cli-options-parser v2.0.0 is a maintenance and hygiene release — no new parsing features, no new APIs to learn. Here's what actually changes for us:

• Breaking: minimum PHP is now 8.0. This drops PHP 7.x support. Audit every environment that runs this tool (local, CI image, staging, prod cron hosts) before bumping. If we can't move off 7.x yet, pin to 1.x and log a debt ticket with a target date — don't let it drift unpinned.
• CI added (GitHub Actions) + Codacy integration: upstream regressions are now caught before we see them, and code-quality trends are visible. Net effect: lower vendor risk for a small dependency.
• Code tidy-up: internal cleanup only. Expect no behavioural change beyond the version floor, but budget a smoke test of our CLI entry points after the bump.
• No new dependencies, still Phalcon-only, still BSD-3.

The value proposition is unchanged from the original assessment — it replaces hand-rolled parsing:

$shortopts = 'v';
$longopts = ['verbose::'];
$options = getopt($shortopts, $longopts);

with this:

$parser = new \Phalcon\Cli\OptionsParser();
$options = $parser->parse(['verbose']);

Tradeoff: Still less feature-rich than Symfony/Console (no argument validation, help generation, or command autocompletion), and this release doesn't close that gap. Recommended for internal tools and lightweight CLIs on PHP 8.0+ Phalcon projects."*