• Accepted Contributions
• Bug Reports
• Support Questions
• Missing Upstream Functionality
• Pull Request Requirements
• Automated Reviews
• Which Branch?
• Quality Checks
• Compiled Assets
• AI-Generated Contributions
• Security Vulnerabilities
• Coding Style
  • PHPDoc
    • Generating Facade Docblocks
• Code of Conduct

Hypervel closely tracks Laravel's public APIs and behavior. To keep the project maintainable, contributions must follow these rules:

Documentation corrections can also be submitted directly.

Pull requests must address one clearly defined problem or change. Include all source changes, tests, and documentation needed to complete the contribution.

Bug-fix code pull requests must explain the root cause and include a regression test that fails without the fix and passes with it.

Performance improvements must include reproducible before-and-after benchmarks, the commands and environment used, and an explanation of any tradeoffs. Tests must verify that supported behavior is preserved.

Submissions that do not meet these requirements will be closed without a detailed review. Meeting the requirements does not guarantee acceptance or a review timetable.

If you are unsure whether a change fits Hypervel's direction, start a GitHub Discussion before opening a pull request.

Hypervel encourages pull requests that fix bugs, not just bug reports. Complete bug-fix pull requests take priority over issue-only reports. You do not need to provide a fix to report a bug.

Bug reports must have a clear title and description and include:

Reproduce the issue yourself before submitting it. Describe a demonstrated failure in supported usage; speculation about what might fail is not sufficient. Report suspected security vulnerabilities privately, not in public issues.

Please search existing issues and discussions before opening a report. If the same issue has already been reported, add new reproduction details there.

Reports that lack the required information will be closed until a complete reproduction is provided.

If a maintainer requests additional information on an existing issue and applies the not enough info label, please respond within 14 days. Issues without a reporter response will be closed with an explanation and can be reconsidered when the information is supplied. A response stops automatic closure while the maintainer assesses it. Issues are not closed merely because they are inactive.

Maintainers must describe the information needed before applying the label. Remove and reapply it when requesting further information after a response. The maintainer-directed label exempts an issue from automatic closure.

If you notice improper DocBlock, PHPStan, or IDE warnings while using Hypervel, do not create a GitHub issue. Instead, please submit a pull request to fix the problem.

The Hypervel source code is managed on GitHub in the hypervel/components repository.

Use GitHub issues for bug reports and potentially missed upstream functionality. Use GitHub Discussions for support questions, ideas, and Hypervel-specific feature proposals. Before proposing a feature, read the accepted contribution rules.

The Hypervel team handles ports and upstream synchronization for Laravel and third-party packages, including Saloon and Spatie's Data and Permission packages. Do not submit pull requests to port upstream functionality or synchronize upstream changes. This restriction does not prevent direct contributions that fix bugs or improve performance, including defects shared with upstream.

If you believe Hypervel has missed existing upstream functionality, first check the affected package's README and documentation for its upstream reference and intentional differences. For Laravel functionality, also check the Laravel porting guide. Recent upstream changes may be awaiting the next sync. Intentionally omitted deprecated or legacy APIs, architectural incompatibilities, and features intentionally excluded from Hypervel's direction are not missing functionality.

If you are unsure whether the functionality belongs in Hypervel, ask in GitHub Discussions before opening a missing-functionality issue.

If the functionality exists upstream and is not an intentional omission, use the missing upstream functionality form. Include the affected Hypervel package and version, links to the upstream implementation and relevant documentation, the upstream branch and full commit SHA you compared against, and a minimal example demonstrating the missing behavior. Search existing issues and tracked deferred work first. The team will assess whether the functionality was missed and handle any required port.

Every pull request must:

Keep unrelated changes in separate pull requests. Do not submit placeholders, unfinished implementations, or changes that depend on the maintainer completing the work. Complete the required local checks before opening a code pull request.

Mark the pull request ready for review only when it meets these requirements and you have addressed the automated review findings. Draft pull requests are not reviewed. External draft pull requests with no contributor activity for seven days will be closed with an explanation. Pushes, edits, and author replies count as activity; bot comments do not. The timer starts when a pull request becomes a draft or is reopened, and existing drafts receive seven days from their first cleanup notice.

Maintainer-authored and bot-authored pull requests are exempt from this draft cleanup. Maintainers must apply the maintainer-directed label to exempt other work they are directing. Ready-for-review pull requests are not closed for inactivity or failing CI.

Hypervel uses automated review tools to identify potential correctness, maintainability, and style issues before maintainer review.

Review bots can report false positives or recommend unnecessary changes. You must investigate every finding. Fix valid issues and reply with an explanation of the correction. For findings that do not apply, reply with evidence explaining why. Do not blindly apply suggestions or dismiss findings without investigation.

Before requesting maintainer review, resolve each finding with a correction or an evidence-backed reply. If a finding remains disputed, explicitly flag the evidence and the decision needed from a maintainer instead. Marking a thread resolved does not replace the required investigation, correction, or reply.

Bug fixes and backward-compatible improvements for the current release must be sent to the current version branch (currently 0.4).

Breaking changes or work intended for the next minor release must be sent to the main branch. Hypervel is pre-1.0, so minor releases may include breaking changes, but those changes must be intentional and documented. Choosing a target branch does not replace the contribution requirements or approval for new Hypervel-specific features.

Before opening a code pull request, run composer fix from the repository root and ensure it completes successfully. Review any formatting changes it produces. Repeat this verification after subsequent code changes, before requesting review.

composer fix

This command formats the framework and skeletons, syncs generated configuration from the formatted defaults, then runs PHPStan, the parallel framework test suite, the Testbench package-mode suite, and the Testbench consumer-package tests. Each skeleton uses its own formatting and analysis configuration. Review and commit the generated config changes alongside the source changes.

Install the base skeleton's dependencies once before running the combined checks:

composer --working-dir=skeletons/hypervel install

The check commands use installed dependencies. They do not install or update packages, build frontend assets, or start application servers.

Investigate and address CI failures before requesting maintainer review. The compiled-assets check may fail while a contributor's source changes await a maintainer rebuild. All checks must pass before merge.

Documentation-only changes do not require the PHP test and analysis suite. Verify the changed instructions, examples, and links, and ensure the applicable CI checks pass.

During development, you can run individual checks to investigate failures. These do not replace the required composer fix run:

composer test:parallel
composer analyse
composer lint
composer lint:fix

To check only the skeletons:

composer lint:skeletons
composer lint:skeletons:fix
composer analyse:skeletons

Use composer check:skeleton-config to verify generated configuration in both the base skeleton and the React starter kit.

The framework and skeleton installation workflows test fresh installations separately in CI. Pull requests, pushes to 0.4, and manual runs use the checked-out packages; nightly runs use the published packages. The skeleton workflow also builds frontend assets, runs application checks, and verifies HTTP startup.

Framework JavaScript uses a shared Vite+ and pnpm workspace. After installing the frontend dependencies, check source and run its tests from the repository root:

pnpm check
pnpm test

Use pnpm check:fix to apply formatting and supported lint fixes. You can select a test project with pnpm test:horizon, pnpm test:telescope, pnpm test:mcp, or pnpm test:wayfinder.

If your change affects Wayfinder's generated TypeScript, also run:

pnpm test:wayfinder
pnpm test:wayfinder:cached
pnpm typecheck:wayfinder

To run the database integration tests, pass the connection name to the database test runner:

bin/run-database-tests.sh mysql
bin/run-database-tests.sh mariadb
bin/run-database-tests.sh pgsql
bin/run-database-tests.sh sqlite

The runner sets DB_CONNECTION from this argument. Configure the remaining database environment variables (see .env.example) before running the command. Any additional ParaTest options are forwarded to each database test suite. For example, you may use bin/run-database-tests.sh pgsql -p 3 --filter=EloquentPrunableTest to control the worker count and select a specific test.

Do not disable checks, skip affected tests, or weaken assertions to make a pull request pass.

Hypervel packages such as Horizon and Telescope include JavaScript and CSS assets for their dashboards. If you are submitting a change that affects dashboard source files, do not commit the generated dist files unless a maintainer asks you to do so. Due to their size, compiled assets cannot realistically be reviewed with the same care as source files. This could be exploited as a way to inject malicious code into Hypervel. In order to defensively prevent this, compiled assets will be generated and committed by Hypervel maintainers when needed.

Framework frontend source lives in the components repository. Horizon, Telescope, the exception renderer, Workbench, Wayfinder, and the AI demo share the root dependency catalog and lockfile. Their split repositories ship compiled assets for Composer consumers; frontend development takes place in a fork of components.

Install Vite+, then run from the repository root:

vp install --frozen-lockfile
vp run check
vp test
vp run build

Vite+ selects the Node.js and pnpm versions declared in the root package.json. You can also use Node.js 24 (24.15 or later) and the exact declared pnpm version directly: run pnpm install --frozen-lockfile, then pnpm check, pnpm test, and pnpm build. Plain pnpm does not switch its own version in this repository.

The root build compiles every framework frontend and the AI demo, and minifies the MCP browser SDK. To build one package, use pnpm build:horizon, pnpm build:telescope, pnpm build:exception-renderer, pnpm build:workbench, or pnpm build:ai-workbench. To rebuild a dashboard as you edit, run pnpm --dir src/horizon watch or pnpm --dir src/telescope watch. The same commands are available through vp run.

Use package-manager commands to update dependencies. Keep shared versions in pnpm-workspace.yaml's catalog and declarations in the packages that use them. After an update, run pnpm audit, including development dependencies, then the checks, tests and builds. Browser dependencies are also declared as development dependencies, so auditing production dependencies alone is insufficient.

Maintainers commit rebuilt Horizon and Telescope dist files, the exception renderer's dist, Workbench's public/build, and the minified MCP SDK alongside the source and lockfile changes. The CI asset check reports changed or new output files. Contributors may leave these generated files for a maintainer to rebuild and review before merge. The AI demo's build output stays untracked. Applications install the distributed assets through Composer and do not need Node.js.

Application skeletons are independent projects. Their manifests and builds do not use the framework workspace or catalog. Follow the skeleton's own installation commands when working on an application.

You are responsible for every part of your submission, including code generated by an agent. Before submitting code, review the complete diff and run the required checks. Verify every claim in any issue or pull request you submit.

You must understand the implementation and be able to explain its behavior, tests, and tradeoffs during review. Do not submit generated findings you have not reproduced or generated changes you have not verified. You must investigate and respond to automated review findings yourself, including false positives.

Bulk automated issue creation or pull request submission is prohibited. Accounts engaging in this behavior will be blocked from the project.

If you discover a security vulnerability within Hypervel, please send an email to Albert Chen at [email protected]. All security vulnerabilities will be promptly addressed.

Hypervel follows the PSR-4 autoloading standard and uses php-cs-fixer to enforce coding style. All PHP files must declare strict types. Use modern PHP 8.4+ features where appropriate.

Parameters, return values, properties, class constants, and closure signatures must be fully typed wherever PHP and inherited signatures permit.

Frontend formatting is configured in the root vite.config.ts. To omit recorded formatting-only commits from local Git blame, run:

git config blame.ignoreRevsFile .git-blame-ignore-revs

Below is an example of a valid Hypervel documentation block:

/**
 * Register a binding with the container.
 *
 * @throws \Exception
 */
public function bind(string|array $abstract, Closure|string|null $concrete = null, bool $shared = false): void
{
    // ...
}

When the @param or @return attributes are redundant due to the use of native types, they can be removed:

/**
 * Execute the job.
 * [tl! remove]
 * @return void [tl! remove]
 */
public function handle(AudioProcessor $processor): void
{
    // ...
}

Use @param and @return annotations to describe types that native declarations cannot express, such as array element types:

/**
 * Get the attachments for the message.
 * [tl! add]
 * @return array<int, \Hypervel\Mail\Mailables\Attachment> [tl! add]
 */
public function attachments(): array
{
    return [
        Attachment::fromStorage('/path/to/file'),
    ];
}

When a change affects a service exposed through a facade, regenerate that facade's docblock from the repository root:

composer facade -- Hypervel\\Support\\Facades\\Cache

You may use the --lint option to check the generated docblock without changing the file:

composer facade -- --lint Hypervel\\Support\\Facades\\Cache

For details about configuring and using the generator in a package, see the package development documentation.

The Hypervel code of conduct is derived from the Ruby code of conduct. Any violations of the code of conduct may be reported to Albert Chen ([email protected]):