Coding & Quality Standards

Pyxis CMS is built on rigorous engineering standards to ensure the core is maintainable, secure, and scalable. Every contribution must adhere to the following principles.

1. Logic Centralization (isLive)

To prevent data leaks and inconsistent visibility across the API, we use a “Single Source of Truth” pattern for content visibility.

The Rule: Never check for status === 'published' directly in Controllers or Services.
Implementation: Always use the $model->isLive() method.
Why?: If we ever change the definition of “live” content (e.g., adding an ‘archived’ state or checking for specific user roles), we only need to update the Model, and the entire API will adapt automatically.

2. API Response Architecture

We do not return raw Eloquent models or arrays. Every API response must be transformed through a JsonResource.

Consistency: All responses must have a root “data” object.
Security: Sensitive fields (like passwords or internal IDs) must be explicitly excluded in the Resource.
Headless Bridge: Resources are responsible for flattening complex relationships into a structure that is “Headless friendly”

3. Database & Identification

Primary Keys: We use UUID (v7) for all models exposed via the API. This prevents ID scraping and increases security.
Foreign Keys: Database-level integrity constraints are mandatory. We never rely solely on application-level logic to maintain data relationships.
Slugs: All public-facing resources must have a unique slug, validated against their parent hierarchy.

4. Coding Style (PHP)

We follow the PER Coding Style 2.0 standard (the successor to PSR-12).

Type Hinting: All function arguments and return types must be explicitly defined.
Strict Types: Every PHP file must start with the declare(strict_types=1); declaration.
Naming Conventions:

Models: Singular (e.g., Page)
Controllers: Resourceful where possible (e.g., PageController)
Traits: Describing a capability (e.g., HasUuids)

5. Frontend Standards

TypeScript: Mandatory for all components. The use of the “any” type is strictly forbidden.
Components: Functional components only, using Tailwind CSS for styling.
Data Fetching: Use Astro Components (SSR/Static), Client Components (React/Vue/Svelte) by default. Client Components should be reserved only for parts requiring interactivity.

6. Git & Commit Messages

We use Conventional Commits to keep the project history readable and professional:

feat: new feature
fix: bug fix
docs: documentation changes
test: adding or updating tests
refactor: code change that neither fixes a bug nor adds a feature

7. Zero-Leak Security

When a resource is marked with visibility: “password”, the API must return a 200 OK status (to allow the frontend to render the password form), but the “content” field must be null. Actual content delivery is only permitted after secondary verification.