docs: document exceptions style

innocenzi · innocenzi · commit 165a8416af0d · 2025-06-26T16:30:11.000+02:00
diff --git a/src/Web/Documentation/content/main/5-extra-topics/03-contributing.md b/src/Web/Documentation/content/main/5-extra-topics/03-contributing.md
@@ -9,33 +9,35 @@ Welcome aboard! We're excited that you are interested in contributing to the Tem
 
 To report an error or a bug, please:
 
-* Head over to the [issue page](https://github.com/tempestphp/tempest-framework/issues) to open an issue.
-* Provide as much context about the problem you are running into and the environment you are running Tempest in.
-* Provide the version and, if relevant, the component you are running into issues with.
-* For a shot at getting our "Perfect Storm" label, submit a PR with a failing test!
+- Head over to the [issue page](https://github.com/tempestphp/tempest-framework/issues) to open an issue.
+- Provide as much context about the problem you are running into and the environment you are running Tempest in.
+- Provide the version and, if relevant, the component you are running into issues with.
+- For a shot at getting our "Perfect Storm" label, submit a PR with a failing test!
 
 Once the issue has been opened, the Tempest team will:
 
 <!-- TODO: Update this section with some links -->
-* Label the issue appropriately.
-* Assign the issue to the appropriate team member.
-* Try and get a response to you as quickly as possible.
+
+- Label the issue appropriately.
+- Assign the issue to the appropriate team member.
+- Try and get a response to you as quickly as possible.
 
 In the event that an issue is opened, but we get no response within 30 days, the issue will be closed.
 
 ## Request a feature
 
 Tempest is a work in progress. We recognize that some features you might benefit from or expect may be missing. If you do have a feature request, please:
 
-* Head over to the [issue page](https://github.com/tempestphp/tempest-framework/issues) to open an issue.
-* Provide as much detail about the feature you are looking for and how it might benefit you and others.
+- Head over to the [issue page](https://github.com/tempestphp/tempest-framework/issues) to open an issue.
+- Provide as much detail about the feature you are looking for and how it might benefit you and others.
 
 Once the feature request has been opened, the Tempest team will:
 
 <!-- TODO: Update this section with some links -->
-* Label the issue appropriately.
-* Ask any clarifying question to help better understand the use case.
-* If the feature requested is accepted, the Tempest team will assign the `{txt}Uncharted waters` label. A Tempest team member or a member of the community can contribute the code for this.
+
+- Label the issue appropriately.
+- Ask any clarifying question to help better understand the use case.
+- If the feature requested is accepted, the Tempest team will assign the `{txt}Uncharted waters` label. A Tempest team member or a member of the community can contribute the code for this.
 
 :::tip
 We welcome all contributions and greatly value your time and effort. To ensure your work aligns with Tempest's vision and avoids unnecessary effort, we aim to provide clear guidance and feedback throughout the process.
@@ -50,47 +52,52 @@ We welcome contributions of any size! Feel free to submit a pull request, even i
 :::
 
 To contribute to Tempest's documentation, please:
-* Head over to the [Tempest docs repository](https://github.com/tempestphp/tempest-docs) to fork the project.
-* Add or edit any relevant documentation in a manner consistent with the rest of the documentation.
-* Re-read what you wrote and run it through a spell checker.
-* Open a pull request with your changes.
+
+- Head over to the [Tempest docs repository](https://github.com/tempestphp/tempest-docs) to fork the project.
+- Add or edit any relevant documentation in a manner consistent with the rest of the documentation.
+- Re-read what you wrote and run it through a spell checker.
+- Open a pull request with your changes.
 
 Once a pull request has been opened, the Tempest team will:
-* Use GitHub reviews to review your pull request.
-* If necessary, ask for revisions.
-* If we decide to pass on your pull request, we will thank you for your contribution and explain our decision. We appreciate all the time contributors put into Tempest!
-* If your pull request is accepted, we will mark it as such and merge it into the project. It will be released in the next tagged version! 🎉
+
+- Use GitHub reviews to review your pull request.
+- If necessary, ask for revisions.
+- If we decide to pass on your pull request, we will thank you for your contribution and explain our decision. We appreciate all the time contributors put into Tempest!
+- If your pull request is accepted, we will mark it as such and merge it into the project. It will be released in the next tagged version! 🎉
 
 ## Contribute code
 
 So, you want to dive into the code. To make the most of your time, please ensure that any contributions pertain to an approved feature request or a confirmed bug. This helps us focus on the vision for Tempest and ensuring the best developer experience.
 
 To contribute to Tempest's code, you will need to first [setup Tempest locally](#setting-up-tempest-locally). Then,
-* Make the relevant code changes.
-* Write tests that verify that your contribution works as expected.
-* Run `composer qa` to ensure you are adhering to our style guidelines.
-* Create a [pull request](https://github.com/tempestphp/tempest-framework/pulls) with your changes.
-* If your pull request is connected to an open issue, add a line in your description that says `{txt}Fixes #xxx`, where `{txt}#xxx` is the number of the issue you're fixing.
+
+- Make the relevant code changes.
+- Write tests that verify that your contribution works as expected.
+- Run `composer qa` to ensure you are adhering to our style guidelines.
+- Create a [pull request](https://github.com/tempestphp/tempest-framework/pulls) with your changes.
+- If your pull request is connected to an open issue, add a line in your description that says `{txt}Fixes #xxx`, where `{txt}#xxx` is the number of the issue you're fixing.
 
 :::tip Pull request titles
 We use [conventional commits](#commit-and-merge-conventions) to automatically generate readable changelogs. You may help with this by providing a clear pull request title, which will appear in the changelog and needs to be understandable without the pull request's content as a context. Read more about this in the [pull requests](#pull-requests) section.
 :::
 
 Once a pull request has been opened, the Tempest team will:
-* Use GitHub reviews to review your pull request.
-* Ensure all CI pipelines are passing.
-* If necessary, ask for revisions.
-* If we decide to pass on your pull request, we will thank you for your contribution and explain our decision. We appreciate all the time contributors put into Tempest!
-* If your pull request is accepted, we will mark it as such and merge it into the project. It will be released in the next tagged version! 🎉
+
+- Use GitHub reviews to review your pull request.
+- Ensure all CI pipelines are passing.
+- If necessary, ask for revisions.
+- If we decide to pass on your pull request, we will thank you for your contribution and explain our decision. We appreciate all the time contributors put into Tempest!
+- If your pull request is accepted, we will mark it as such and merge it into the project. It will be released in the next tagged version! 🎉
 
 ### Setting up Tempest locally
 
-* Install PHP.
-* Install Composer.
-* Install [Bun](https://bun.sh) or Node.
-* [Fork and clone](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the Tempest repository.
+- Install PHP.
+- Install Composer.
+- Install [Bun](https://bun.sh) or Node.
+- [Fork and clone](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) the Tempest repository.
 
 In your terminal, run:
+
 ```sh
 cd /path/to/your/clone
 composer update
@@ -108,16 +115,16 @@ Add the following in your `composer.json`, replacing `{txt}/path/to/your/clone`
 
 ```json
 {
-  // ...
-  "repositories": [
-    {
-      "type": "path",
-      "url": "/path/to/your/clone"
-    }
-  ],
-  "minimum-stability": "dev",
-  "prefer-stable": true
-  // ...
+	// ...
+	"repositories": [
+		{
+			"type": "path",
+			"url": "/path/to/your/clone"
+		}
+	],
+	"minimum-stability": "dev",
+	"prefer-stable": true
+	// ...
 }
 ```
 
@@ -133,7 +140,7 @@ bun install /Users/you/Code/forks/tempest/packages/vite-plugin-tempest
 
 Do not forget to run `bun dev` in the root of your local version of the framework, so your changes can be reflected on your local application without needing to run `bun build` each time.
 
-### Styling decisions
+### Code style and conventions
 
 Tempest uses a modified version of PSR-12. We automate the entire styling process because we know everyone is used to different standards and workflows. To see some of the rules we enforce, check out our [Mago](https://github.com/tempestphp/tempest-framework/blob/main/mago.toml) and [Rector](https://github.com/tempestphp/tempest-framework/blob/main/rector.php) configurations.
 
@@ -143,8 +150,8 @@ The following outlines some other guidelines we have established for Tempest.
 
 Whenever possible, classes should be `final` and `readonly`. This practice promotes immutability and prevents inadvertent changes to logic.
 
-:::tip
-You may watch this [video](https://www.youtube.com/watch?v=HiD6CwWq5Ds&ab_channel=PHPAnnotated) to understand my thoughts about using `final`.
+:::tip{tabler:bulb}
+You may watch this [video](https://www.youtube.com/watch?v=HiD6CwWq5Ds&ab_channel=PHPAnnotated) to understand {x:brendt_gd}'s thoughts about using `final`.
 :::
 
 ---
@@ -153,53 +160,77 @@ You may watch this [video](https://www.youtube.com/watch?v=HiD6CwWq5Ds&ab_channe
 
 Tempest uses a modified version of the [.NET best practices](https://learn.microsoft.com/en-us/previous-versions/dotnet/netframework-4.0/ms229043(v=vs.100)?redirectedfrom=MSDN) for acronym casing. Please see below for our guidelines:
 
-__Do capitalize all characters of two to three character acronyms, except the first word of a camel-cased identifier.__
+**Do capitalize all characters of two to three character acronyms, except the first word of a camel-cased identifier.**
 A class named `IPAddress` is an example of a short acronym (IP) used as the first word of a Pascal-cased identifier. A parameter named `ipAddress` is an example of a short acronym (ip) used as the first word of a camel-cased identifier.
 
-__Do capitalize only the first character of acronyms with four or more characters, except the first word of a camel-cased identifier.__
+**Do capitalize only the first character of acronyms with four or more characters, except the first word of a camel-cased identifier.**
 A class named `UuidGenerator` is an example of a long acronym (Uuid) used as the first word of a Pascal-cased identifier. A parameter named `uuidGenerator` is an example of a long acronym (uuid) used as the first word of a camel-cased identifier.
 
-__Do not capitalize any of the characters of any acronyms, whatever their length, at the beginning of a camel-cased identifier.__
+**Do not capitalize any of the characters of any acronyms, whatever their length, at the beginning of a camel-cased identifier.**
 A class named `Uuid` is an example of a long acronym (Uuid) used as the first word of a camel-cased identifier. A parameter named `dbUsername` is an example of a short acronym (db) used as the first word of a camel-cased identifier.
 
 ---
 
-#### Validation class formatting
+#### Validation classes
 
-1. __Error message formatting__:
-    - __Avoid ending punctuation__. When writing error messages for validation rules, refrain from including ending punctuation such as periods, exclamation marks, or question marks. This helps in maintaining a uniform style and prevents inconsistency in error message presentation.
+When writing error messages for validation rules, **refrain from including ending punctuation** such as periods, exclamation marks, or question marks. This helps in maintaining a uniform style and prevents inconsistency in error message presentation.
 
 ```diff
 - Value should be a valid email address!
 + Value should be a valid email address
 ```
 
+---
+
+#### Exception classes
+
+Exception classes can be thought of as events and should be named accordingly. Use a subject-verb structure in the past tense to describe what happened (e.g., `DatabaseOperationFailed`, `StorageUsageWasForbidden`, `AuthenticatedUserWasMissing`).
+
+- Do not suffix class names with `Exception`; the context of `throw` or `catch` language constructs makes their purpose clear.
+- All exception classes must extend PHP's built-in `\Exception`.
+- When appropriate, define marker interfaces such as `CacheException`, `DatabaseException`, or `FilesystemException` to group related exceptions. These interfaces must be suffixed with `Exception`.
+- Set the exception message within the exception class itself—not where it is thrown.
+- Override the constructor to only accept relevant context-specific input.
+
+For instance, the following exception accepts a the relevant cache key as a constructor argument, and keeps it accessible through a public property:
+
+```php LockAcquisitionTimedOut.php
+final class LockAcquisitionTimedOut extends Exception implements CacheException
+{
+    public function __construct(
+        public readonly string $key,
+    ) {
+        parent::__construct("Lock with key `{$key}` could not be acquired on time.");
+    }
+}
+```
+
 ## Release workflow
 
 Tempest uses sub-splits to allow components to be installed as individual packages. The following outlines how this process works.
 
 ### Workflow steps
 
 1. **Trigger event**
-    - When a pull request is merged, or a new tag is created, the `.github/workflows/subsplit-packages.yml` action is run.
+   - When a pull request is merged, or a new tag is created, the `.github/workflows/subsplit-packages.yml` action is run.
 
 2. **Package information retrieval**
-    - When the `subsplit-packages.yml` is run, it calls `bin/get-packages`.
-    - This PHP script uses a combination of Composer and the filesystem to return (in JSON) some information about every package. It returns the:
-        - **Directory**
-        - **Name**
-        - **Package**
-        - **Organization**
-        - **Repository**
+   - When the `subsplit-packages.yml` is run, it calls `bin/get-packages`.
+   - This PHP script uses a combination of Composer and the filesystem to return (in JSON) some information about every package. It returns the:
+     - **Directory**
+     - **Name**
+     - **Package**
+     - **Organization**
+     - **Repository**
 
 3. **Action matrix creation**
-    - The result of the `get-packages` command is then used to create an action matrix.
-    - This ensures that the next steps are performed for _every_ package discovered.
+   - The result of the `get-packages` command is then used to create an action matrix.
+   - This ensures that the next steps are performed for _every_ package discovered.
 
 4. **Monorepo split action**
-    - The `symplify/monorepo-split-github-action@v2.3.0` GitHub action is called for every package and provided the necessary information (destination repo, directory, etc.).
-    - This action takes any changes and pushes them to the sub-split repository determined by combining the "Organization" and "Repository" values returned in step 2.
-    - Depending on whether a tag is found or not, a tag is also supplied so the repository is tagged appropriately.
+   - The `symplify/monorepo-split-github-action@v2.3.0` GitHub action is called for every package and provided the necessary information (destination repo, directory, etc.).
+   - This action takes any changes and pushes them to the sub-split repository determined by combining the "Organization" and "Repository" values returned in step 2.
+   - Depending on whether a tag is found or not, a tag is also supplied so the repository is tagged appropriately.
 
 ## Commit and merge conventions
 
