masitings/geni-api
A Laravel/PHP package that provides a simple client for the Geni API, helping developers authenticate and send requests to Geni services from their applications. It streamlines integration with clean, framework-friendly configuration and straightforward access to genealogy data.
What this release is. v3.1.0 is a minor, non-breaking follow-up to the 3.0 line of a Laravel documentation/spec generation package (config published as config/geni.php, endpoint metadata via PHPDoc and #[Endpoint(...)] attributes, first-class support for Laravel Actions). It adds one authoring feature, removes dead config, and does a documentation/wording pass.
Architecture fit. The package sits in the developer-tooling layer, not the request path. It introspects routes/actions and PHPDoc at build or CI time to emit committed specification documents. That is a good architectural fit for teams that want specs versioned alongside code and reviewed in PRs: no runtime dependency, no sidecar service, no production traffic exposure. The @summary tag strengthens this by letting the spec's human-facing title be authored rather than inferred, which matters if the spec is consumed by consumers, portals, or SDK generators. Precedence is explicit and sensible (#[Endpoint(title: ...)] attribute > @summary > first PHPDoc paragraph > class-name derivation), so existing projects have a deterministic fallback chain.
Integration feasibility. High for a Laravel shop already on 3.0.x. This is a drop-in minor: no behavioral changes for existing documents, existing committed specs remain valid, and only adopting @summary changes output. The config-key removal is the only item requiring a decision, and it is low-risk precisely because those keys were never read — leaving them in a published config/geni.php is inert. Feasibility drops for teams not on Laravel Actions or not using PHPDoc as their metadata surface.
Technical risk. Low-to-moderate, and mostly not from this release.
Key questions for the maintainer. (1) Is @summary supported on all metadata surfaces — controllers, invokable actions, closures — or only where PHPDoc is parsed? (2) Does @summary participate in title-deduplication/grouping (e.g., two endpoints with the same summary)? (3) Will the removed config keys produce a deprecation notice, or silently do nothing? (4) Is a JSON Schema/OpenAPI diff of generated output published per release so we can regression-check committed specs in CI? (5) What is the documented support window for 3.0.x now that 3.1 is out?
Stack fit. Requires a Laravel application with route registration and PHPDoc annotations; the strongest fit is a team already using Laravel Actions, where the class-name-derived title fallback means many endpoints need no annotation at all until a better title is wanted. Non-Laravel PHP or Laravel apps with dynamically constructed/closure-based routes will get less value and should be scoped out of a first pilot.
Migration path. Treat this as a patch-level adoption, not a project.
^3.1 in a single low-traffic service first.config/geni.php files untouched (the removed keys are unread), or clean them up opportunistically in a separate, clearly-labeled chore commit so it never masks a real spec diff.@summary selectively — start with endpoints whose auto-derived titles are known-poor (acronym classes, Action/Handler suffixes, nested namespaces) rather than sweeping the codebase.Compatibility. Backward compatible for documents; forward risk is nil for consumers since output is unchanged unless @summary is used. The real compatibility surface is the authoring surface — if a team later wants to standardize titles, they are committing to PHPDoc as the source of truth for a user-visible string, which should be a conscious choice.
Sequencing. (a) Pin and diff-verify output equivalence; (b) add a CI check that regenerating the spec in a clean environment produces no diff from the committed file (this is the highest-value control here, and it retroactively protects you from any future minor); (c) pilot @summary on 3–5 endpoints and confirm consumer/portal rendering; (d) codify precedence order and the @summary convention in the team's API style guide; (e) only then consider normalizing titles repo-wide.
Maintenance. Near-zero incremental cost. This is a pinned Composer dev-dependency; the ongoing work is the spec artifact itself, not the tool. Budget continuous attention for one thing only: keeping committed specs in sync with code, which the CI no-diff check enforces cheaply. The dead-config cleanup slightly reduces future maintenance by removing keys that invite "why is this here?" investigations.
Support. Internal support should be simple: one owner (API platform or backend guild) curates the style guide and reviews spec diffs; feature teams write annotations. External support depends on the maintainer's responsiveness and on how closely 3.1.x tracks 3.0.x. The docs-rewording pass is a mild support liability in the near term — prior search results, blog posts, and internal notes referencing other generators will be stale, so expect a short window of "the docs don't match what I read elsewhere." The absence of a stated deprecation policy for 3.0.x is the main open support question.
Scaling. Scales well structurally: generation is offline and parallelizable, so cost grows with route count and CI minutes, not with production traffic. Two scaling thresholds to watch. First, artifact size/PR noise — as the API grows, spec diffs get harder to review, so consider splitting specs by domain or module before that becomes painful. Second, title consistency — class-name derivation scales technically but not editorially; past a few dozen endpoints, inconsistent titles become a real consumer-facing quality problem, which is exactly the gap @summary addresses and why a convention (not ad-hoc usage) is worth establishing early. No runtime scaling concerns exist by design.
Failure modes. (1) Silent spec drift — developers change routes without regenerating; mitigated by the CI no-diff gate. (2) Title regression — a developer adds @summary inconsistently or a class rename silently changes a fallback-derived title; the diff review catches this if diffs are actually read. (3) Annotation-only documentation debt — PHPDoc used as the metadata channel decays faster than typed attributes; watch for endpoints with missing or stale annotations, and lean on #[Endpoint] where correctness matters more than convenience. (4) Config ambiguity — leftover removed keys creating false confidence that a setting is active. (5) Major-version re-adoption cost — as with any post-major release, pinning loosely risks pulling in 3.x-era changes you haven't validated against the CI gate. All of these are cheap to detect and cheap to fix; none are production-affecting.
Ramp-up. Low. A Laravel developer familiar with PHPDoc and attributes needs well under a day to be productive: publish config, generate, read the precedence rules, optionally add @summary. The one-time onboarding friction is organizational — establishing the style guide, agreeing that specs are committed and reviewed, and wiring the CI drift check — roughly a day of platform work, not per-developer training. Teams migrating from another generator should budget extra for porting existing annotations and for un-learning stale conventions that the reworded docs no longer reinforce.
How can I help you explore Laravel packages today?