diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..8a5f881 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,70 @@ +name: Bug report +description: Report a reproducible problem +title: "[Bug]: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug. Please include enough detail to reproduce it. + - type: textarea + id: summary + attributes: + label: Summary + description: What is wrong? + placeholder: Clear and short description of the bug. + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: Share exact commands, config, and steps. + placeholder: | + 1. Run `composer ic:tests` + 2. ... + 3. Observe ... + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + placeholder: What did you expect to happen? + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + placeholder: What happened instead? Include full error output if possible. + validations: + required: true + - type: input + id: php_version + attributes: + label: PHP version + placeholder: "e.g. 8.3.8" + validations: + required: true + - type: input + id: composer_version + attributes: + label: Composer version + placeholder: "e.g. 2.9.2" + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment details + description: OS, CI provider, shell, and anything else relevant. + placeholder: Ubuntu 24.04, GitHub Actions, bash... + validations: + required: true + - type: textarea + id: additional + attributes: + label: Additional context + description: Links, screenshots, logs, or related issues. diff --git a/.github/ISSUE_TEMPLATE/ci_failure.yml b/.github/ISSUE_TEMPLATE/ci_failure.yml new file mode 100644 index 0000000..3dcbac9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/ci_failure.yml @@ -0,0 +1,48 @@ +name: CI failure +description: Report a reproducible CI or workflow failure +title: "[CI]: " +labels: + - ci +body: + - type: markdown + attributes: + value: | + Use this form when CI fails unexpectedly and can be reproduced. + - type: input + id: workflow + attributes: + label: Workflow/job name + placeholder: security-standards / phpforge + validations: + required: true + - type: input + id: run_url + attributes: + label: Failing run URL + placeholder: https://github.com/OWNER/REPOSITORY/actions/runs/... + validations: + required: true + - type: textarea + id: command + attributes: + label: Failing command + description: Exact command or step that failed. + placeholder: composer ic:ci + validations: + required: true + - type: textarea + id: logs + attributes: + label: Error output + description: Paste the relevant error section. + render: shell + validations: + required: true + - type: textarea + id: local_check + attributes: + label: Local reproduction + description: Can you reproduce locally? If yes, include steps. + placeholder: Yes/No + details + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..3ba13e0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPLATE/docs_improvement.yml b/.github/ISSUE_TEMPLATE/docs_improvement.yml new file mode 100644 index 0000000..80b9607 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/docs_improvement.yml @@ -0,0 +1,34 @@ +name: Docs improvement +description: Report missing, unclear, or incorrect documentation +title: "[Docs]: " +labels: + - documentation +body: + - type: textarea + id: location + attributes: + label: Documentation location + description: File path or URL. + placeholder: README.md section "Quick Start" + validations: + required: true + - type: textarea + id: issue + attributes: + label: What is unclear or incorrect? + placeholder: This section says... + validations: + required: true + - type: textarea + id: suggestion + attributes: + label: Suggested improvement + description: Propose revised wording, structure, or examples. + placeholder: It would be clearer if... + validations: + required: true + - type: textarea + id: additional + attributes: + label: Additional context + description: Related links, screenshots, or prior discussions. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..cc29614 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,44 @@ +name: Feature request +description: Suggest an improvement or new capability +title: "[Feature]: " +labels: + - enhancement +body: + - type: markdown + attributes: + value: | + Thanks for the idea. Please describe the use case first, then the proposed solution. + - type: textarea + id: problem + attributes: + label: Problem or use case + description: What limitation are you hitting? + placeholder: I need to... + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: What should happen? + placeholder: Add a command/config/workflow option that... + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: Any workaround or alternative approach you evaluated. + - type: textarea + id: impact + attributes: + label: Expected impact + description: Who benefits and what changes for users/CI? + placeholder: This would improve... + validations: + required: true + - type: textarea + id: additional + attributes: + label: Additional context + description: Related issues, links, examples, or prior art. diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..2ca776f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,40 @@ +name: Question +description: Ask a usage or integration question +title: "[Question]: " +labels: + - question +body: + - type: markdown + attributes: + value: | + Use this form for usage questions. For confirmed defects, use the bug report form. + - type: textarea + id: context + attributes: + label: What are you trying to do? + description: Describe your goal and expected outcome. + placeholder: I want to... + validations: + required: true + - type: textarea + id: attempted + attributes: + label: What have you tried? + description: Include commands, config snippets, or links you already checked. + placeholder: I tried... + validations: + required: true + - type: textarea + id: output + attributes: + label: Current output or behavior + description: Include relevant command output, logs, or errors. + render: shell + - type: textarea + id: environment + attributes: + label: Environment details + description: PHP version, Composer version, OS, CI provider (if relevant). + placeholder: PHP 8.3, Composer 2.9, Ubuntu 24.04... + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/regression_report.yml b/.github/ISSUE_TEMPLATE/regression_report.yml new file mode 100644 index 0000000..36392bc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/regression_report.yml @@ -0,0 +1,51 @@ +name: Regression report +description: Report behavior that previously worked but now fails +title: "[Regression]: " +labels: + - regression + - bug +body: + - type: textarea + id: summary + attributes: + label: Regression summary + placeholder: This worked before, but now... + validations: + required: true + - type: input + id: last_known_good + attributes: + label: Last known working version/commit + placeholder: v1.2.3 or abc1234 + validations: + required: true + - type: input + id: first_bad + attributes: + label: First broken version/commit + placeholder: v1.2.4 or def5678 + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + placeholder: | + 1. ... + 2. ... + 3. ... + validations: + required: true + - type: textarea + id: expected_actual + attributes: + label: Expected vs actual behavior + placeholder: Expected ..., but got ... + validations: + required: true + - type: textarea + id: environment + attributes: + label: Environment details + description: PHP version, Composer version, OS, CI provider (if relevant). + placeholder: PHP 8.3, Composer 2.9, Ubuntu 24.04... + validations: + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..59ae734 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,33 @@ +## Summary + +Describe what changed and why. + +## Related Issues + +Link issues with `Closes #...` or `Relates #...`. + +## Type of Change + +- [ ] Bug fix +- [ ] New feature +- [ ] Refactor +- [ ] Documentation update +- [ ] CI or tooling update +- [ ] Other (describe in summary) + +## Validation + +List the commands you ran and their result. + +```bash +composer ic:tests +``` + +If full suite was not run, explain why and list focused checks. + +## Checklist + +- [ ] I followed `CONTRIBUTING.md`. +- [ ] I added or updated tests for behavior changes. +- [ ] I updated docs/config/examples when needed. +- [ ] I confirmed no security-sensitive data is exposed. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 62d44a8..9c2638f 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,126 +1,50 @@ -# Contributor Covenant Code of Conduct +# Code of Conduct -## Our Pledge +## Our Commitment -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, religion, or sexual identity -and orientation. +We are committed to making participation in this project a harassment-free +experience for everyone, regardless of age, body size, disability, ethnicity, +gender identity and expression, level of experience, nationality, personal +appearance, race, religion or sexual identity and orientation. -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. +## Expected Behavior -## Our Standards +Examples of behavior that contributes to a positive environment: -Examples of behavior that contributes to a positive environment for our -community include: +- Be respectful and constructive. +- Assume good intent and ask clarifying questions. +- Give and receive feedback professionally. +- Focus on what is best for the community and project. -- Demonstrating empathy and kindness toward other people -- Being respectful of differing opinions, viewpoints, and experiences -- Giving and gracefully accepting constructive feedback -- Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -- Focusing on what is best not just for us as individuals, but for the - overall community +## Unacceptable Behavior Examples of unacceptable behavior include: -- The use of sexualized language or imagery, and sexual attention or - advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or email - address, without their explicit permission -- Other conduct which could reasonably be considered inappropriate in a - professional setting +- Harassment, discrimination or personal attacks. +- Trolling, insulting or derogatory comments. +- Publishing private information without consent. +- Any conduct that is inappropriate in a professional setting. ## Enforcement Responsibilities -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for -moderation decisions when appropriate. +Project maintainers are responsible for clarifying and enforcing this code of +conduct. They may remove, edit or reject comments, commits, code, issues, and +other contributions that violate this policy. ## Scope -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official email address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at -infocyph@gmail.com. -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. +This code of conduct applies in all project spaces, including: -### 2. Warning +- Issue trackers +- Pull requests +- Discussions and chat related to the project +- Any public or private communication where someone represents the project -**Community Impact**: A violation through a single incident or series -of actions. +## Reporting -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or -permanent ban. +To report unacceptable behavior, contact project maintainers privately. -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within -the community. - -## Attribution - -This Code of Conduct is adapted from the Contributor Covenant, version 2.1, -available at: -https://www.contributor-covenant.org/version/2/1/code_of_conduct.html - -Community Impact Guidelines were inspired by Mozilla's code of conduct -enforcement ladder: -https://github.com/mozilla/diversity +## Enforcement -For answers to common questions about this code of conduct, see: -https://www.contributor-covenant.org/faq +Maintainers may take any action they deem appropriate, including warnings, +temporary bans or permanent bans from community participation. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9950065 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,68 @@ +# Contributing + +Thanks for contributing. + +## Before You Start + +- Review the project code of conduct. +- For security issues, use private reporting and avoid opening a public issue. +- Check existing issues and pull requests first to avoid duplicates. + +## Local Setup + +Requirements: + +- See `README.md` for current PHP and Composer requirements. + +Install dependencies: + +```bash +composer install +``` + +## Development Workflow + +Typical contributor workflow: + +1. Create a branch from `main`. +2. Make focused changes. +3. Run quality checks locally. +4. Open a pull request with context and verification notes. + +Recommended checks: + +```bash +composer ic:tests +``` + +Useful targeted commands: + +```bash +composer ic:test:syntax +composer ic:test:code +composer ic:test:lint +composer ic:test:sniff +composer ic:test:static +composer ic:test:security +composer ic:test:architecture +``` + +Auto-fix and processing helpers: + +```bash +composer ic:process +``` + +## Pull Request Guidelines + +- Keep pull requests scoped to one logical change. +- Include why the change is needed and what behavior changed. +- Add or update tests when behavior changes. +- Update docs when command behavior, config, or workflow behavior changes. +- Ensure CI is green before requesting review. + +## Reporting Bugs and Requesting Features + +- Use issue templates for bugs, regressions, CI failures, documentation updates, questions, and feature requests. +- Include reproducible steps, expected behavior, and actual behavior. +- Share environment details (PHP version, OS, Composer version). diff --git a/README.md b/README.md index 5437fb2..3d34e51 100644 --- a/README.md +++ b/README.md @@ -88,3 +88,20 @@ The shared byte-level encoder is available as - NanoID: https://github.com/ai/nanoid - CUID2: https://github.com/paralleldrive/cuid2 - TBSL note: https://github.com/infocyph/UID/blob/main/TBSL.md + +## Security + +Protected by [PHPForge](https://github.com/infocyph/PHPForge) — an automated quality and security gate for PHP projects. + +--- + +
+ Made with ❤️ for the PHP community
+ MIT Licensed
+ Documentation • + Security • + Code of Conduct • + Contributing • + Report Bug • + Request Feature +
diff --git a/SECURITY.md b/SECURITY.md index 40ec122..37a355e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,19 +2,14 @@ ## Supported Versions -Security fixes are provided for the latest major release line. - -| Version | Supported | -|---------| --- | -| `4.x` | ✅ | -| `< 4.0` | ❌ | +The project currently supports security updates for the latest release. ## Reporting a Vulnerability Please report vulnerabilities privately. 1. Use GitHub private vulnerability reporting for this repository (`Security` -> `Advisories` -> `Report a vulnerability`). -2. If private reporting is unavailable, email: `infocyph@gmail.com`. +2. If private reporting is unavailable, contact maintainers through a private channel. 3. Do not open a public issue for security vulnerabilities. Please include: @@ -27,28 +22,28 @@ Please include: ## Response Process -- Initial acknowledgment target: within 3 business days -- Triage target: within 7 business days +- Initial acknowledgment: best effort, typically within a few days +- Triage: best effort, based on maintainer availability - Fix and release timeline depends on severity and exploitability If a report is accepted, a patched release will be prepared and published. Credit will be provided unless you request otherwise. -## Disclosure Policy - -This project follows coordinated disclosure: - -- Keep details private until a fix is released -- Publish advisory/release notes after remediation -- Share CVE information when applicable - -## Scope +## Protected by PHPForge -In scope: +This project is protected by [PHPForge](https://github.com/infocyph/PHPForge), an automated quality and security tooling layer for Infocyph PHP projects. -- Vulnerabilities in code under `src/` -- Supply-chain risks introduced by direct dependencies +PHPForge helps keep the project reliable by running checks for: -Out of scope: +- Code style and standards +- Tests and syntax validation +- Static analysis and type safety +- Security and taint analysis +- Dependency vulnerability audit +- Architecture boundary validation +- Duplicate-code detection +- API snapshot and comment-policy checks +- Refactor safety checks +- Benchmark and release-readiness checks +- Git hooks and CI workflow protection -- Issues only affecting unsupported versions -- Local-only misconfiguration without a library defect +These automated gates strengthen code quality, reduce security risk and help prevent regressions before merge or release. diff --git a/src/functions.php b/src/functions.php index 0c1b63d..7923b1e 100644 --- a/src/functions.php +++ b/src/functions.php @@ -398,17 +398,13 @@ function tbsl(int $machineId = 0, bool $sequenced = false): string if (!function_exists('tbsl_to_base')) { function tbsl_to_base(string $id, int $base): string { - $family = 'tbsl'; - - return __uid_base_call($family, 'toBase', $id, $base); + return TBSL::toBase($id, $base); } } if (!function_exists('tbsl_from_base')) { function tbsl_from_base(string $encoded, int $base): string { - $method = 'fromBase'; - - return __uid_base_call('tbsl', $method, $encoded, $base); + return TBSL::fromBase($encoded, $base); } } @@ -444,17 +440,23 @@ function tbsl_is_valid(string $id): bool if (!function_exists('snowflake_to_base')) { function snowflake_to_base(string $id, int $base): string { - $family = 'snowflake'; - - return __uid_base_call($family, 'toBase', $id, $base); + return __uid_base_call( + family: 'snowflake', + method: 'toBase', + value: $id, + base: $base, + ); } } if (!function_exists('snowflake_from_base')) { function snowflake_from_base(string $encoded, int $base): string { - $method = 'fromBase'; - - return __uid_base_call('snowflake', $method, $encoded, $base); + return __uid_base_call( + family: 'snowflake', + method: 'fromBase', + value: $encoded, + base: $base, + ); } } @@ -474,13 +476,17 @@ function randflake_from_base(string $encoded, int $base): string if (!function_exists('sonyflake_to_base')) { function sonyflake_to_base(string $id, int $base): string { - return Sonyflake::toBase($id, $base); + $family = 'sonyflake'; + + return __uid_base_call($family, 'toBase', $id, $base); } } if (!function_exists('sonyflake_from_base')) { function sonyflake_from_base(string $encoded, int $base): string { - return Sonyflake::fromBase($encoded, $base); + $method = 'fromBase'; + + return __uid_base_call('sonyflake', $method, $encoded, $base); } }