Merge pull request #11 from angelxmoreno/feature/docs

Feature/docs
angelxmoreno · Jun 10, 2023 · 10d9ee3 · 10d9ee3
2 parents de9f189 + 64d79d4
commit 10d9ee3
Show file tree

Hide file tree

Showing 22 changed files with 624 additions and 31 deletions.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -1,25 +1,34 @@
-## Contributor Code of Conduct
+# Contributor Code of Conduct
 
 As contributors and maintainers of the WPRestClient project, we pledge to follow the guidelines outlined in this code of
 conduct to ensure a welcoming and inclusive environment for everyone. We value the participation of all contributors and
 aim to foster a positive and respectful community.
 
-### Guidelines
+## Guidelines
 
-1. **Be Respectful:** Treat all individuals with respect and kindness, regardless of their background, experience level, or opinions.
-2. **Embrace Diversity:** Embrace and celebrate diversity in all forms, including but not limited to race, ethnicity, nationality, gender identity, sexual orientation, religion, age, and abilities.
-3. **Open Communication:** Encourage open and constructive communication. Listen attentively and be considerate of others' ideas and perspectives.
-4. **Constructive Feedback:** Provide feedback in a constructive and respectful manner. Focus on the issue at hand and avoid personal attacks or derogatory language.
-5. **No Harassment:** Harassment, trolling, or any form of disrespectful or offensive behavior will not be tolerated. This includes, but is not limited to, offensive comments, sexual advances, and any other behavior that creates an unsafe or uncomfortable environment.
-6. **Respect Privacy:** Respect the privacy and confidentiality of others. Do not share personal information without explicit consent.
-7. **Collaboration and Cooperation:** Strive for collaboration and cooperation among contributors. Help each other, share knowledge, and support fellow contributors.
+1. **Be Respectful:** Treat all individuals with respect and kindness, regardless of their background, experience level,
+   or opinions.
+2. **Embrace Diversity:** Embrace and celebrate diversity in all forms, including but not limited to race, ethnicity,
+   nationality, gender identity, sexual orientation, religion, age, and abilities.
+3. **Open Communication:** Encourage open and constructive communication. Listen attentively and be considerate of
+   others' ideas and perspectives.
+4. **Constructive Feedback:** Provide feedback in a constructive and respectful manner. Focus on the issue at hand and
+   avoid personal attacks or derogatory language.
+5. **No Harassment:** Harassment, trolling, or any form of disrespectful or offensive behavior will not be tolerated.
+   This includes, but is not limited to, offensive comments, sexual advances, and any other behavior that creates an
+   unsafe or uncomfortable environment.
+6. **Respect Privacy:** Respect the privacy and confidentiality of others. Do not share personal information without
+   explicit consent.
+7. **Collaboration and Cooperation:** Strive for collaboration and cooperation among contributors. Help each other,
+   share knowledge, and support fellow contributors.
 
-### Reporting Issues
-If you encounter any violations of this code of conduct or witness behavior that goes against the principles outlined 
-here, please report it to the project maintainers at [WPRestClient@gmail.com](mailto:WPRestClient@gmail.com). All 
-reports will be reviewed and treated with strict confidentiality. We are committed to maintaining a positive community 
+## Reporting Issues
+
+If you encounter any violations of this code of conduct or witness behavior that goes against the principles outlined
+here, please report it to the project maintainers at [WPRestClient@gmail.com](mailto:WPRestClient@gmail.com). All
+reports will be reviewed and treated with strict confidentiality. We are committed to maintaining a positive community
 and will take appropriate action to address any issues.
 
-By participating in the WPRestClient project, you are expected to adhere to this code of conduct throughout all 
+By participating in the WPRestClient project, you are expected to adhere to this code of conduct throughout all
 interactions and engagements within the project community. This code of conduct is adapted from the Contributor Covenant
 (version 2.0), available at [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html].
diff --git a/CONTRIBUTION_GUIDELINES.md b/CONTRIBUTION_GUIDELINES.md
@@ -1,24 +1,28 @@
 # Contribution Guidelines
 
-We welcome and appreciate contributions to the WPRestClient project. To ensure a smooth and collaborative process, 
+We welcome and appreciate contributions to the WPRestClient project. To ensure a smooth and collaborative process,
 please take a moment to review the following guidelines.
 
 ## Code of Conduct
 
-Please familiarize yourself with our [Code of Conduct](CODE_OF_CONDUCT.md) to understand the expected behavior and 
+Please familiarize yourself with our [Code of Conduct](CODE_OF_CONDUCT.md) to understand the expected behavior and
 conduct within our project community.
 
 ## Ways to Contribute
 
 There are several ways you can contribute to WPRestClient:
 
-1. **Reporting Issues:** If you come across any bugs, issues, or have feature requests, please open an issue on our [GitHub repository](link-to-issues) and provide a detailed description.
+1. **Reporting Issues:** If you come across any bugs, issues, or have feature requests, please open an issue on
+   our [GitHub repository](https://github.com/angelxmoreno/WPRestClient/issues) and provide a detailed description.
 
-2. **Bug Fixes and Enhancements:** You can contribute by fixing bugs or enhancing existing features. Fork the repository, make your changes in a new branch, and submit a pull request.
+2. **Bug Fixes and Enhancements:** You can contribute by fixing bugs or enhancing existing features. Fork the
+   repository, make your changes in a new branch, and submit a pull request.
 
-3. **Documentation:** Improvements to documentation are highly appreciated. If you notice any areas that need clarification or have suggestions for better explanations, feel free to submit a pull request.
+3. **Documentation:** Improvements to documentation are highly appreciated. If you notice any areas that need
+   clarification or have suggestions for better explanations, feel free to submit a pull request.
 
-4. **Testing:** Help improve the reliability and stability of the library by writing and running tests. Contributions that include new test cases or improve test coverage are valuable.
+4. **Testing:** Help improve the reliability and stability of the library by writing and running tests. Contributions
+   that include new test cases or improve test coverage are valuable.
 
 ## Getting Started
 
@@ -32,7 +36,8 @@ There are several ways you can contribute to WPRestClient:
 4. Make your changes, additions, or fixes in a new branch, ensuring clear and concise commit messages.
 5. Test your changes thoroughly to ensure they don't introduce new issues.
 6. Push your changes to your forked repository.
-7. Submit a pull request to the `main` branch of the WPRestClient repository. Provide a detailed description of your changes and the problem they solve.
+7. Submit a pull request to the `main` branch of the WPRestClient repository. Provide a detailed description of your
+   changes and the problem they solve.
 
 ## Pull Request Guidelines
 
@@ -47,8 +52,8 @@ There are several ways you can contribute to WPRestClient:
 
 By contributing to WPRestClient, you agree that your contributions will be licensed under the [MIT License](LICENSE).
 
-We appreciate your valuable contributions to the project! Thank you for helping us improve WPRestClient and make it 
+We appreciate your valuable contributions to the project! Thank you for helping us improve WPRestClient and make it
 even better.
 
-If you have any questions or need further assistance, feel free to reach out to 
+If you have any questions or need further assistance, feel free to reach out to
 [WPRestClient@gmail.com](mailto:WPRestClient@gmail.com)
diff --git a/README.md b/README.md
@@ -1,17 +1,19 @@
 # WPRestClient
 
-## Currently under development
-
 WPRestClient is a PHP library for seamless interaction with WordPress sites via the WordPress RESTful API, simplifying
 authentication, data retrieval, and content management tasks
 
 ## Features
 
 - Connect to WordPress sites and authenticate using REST API authentication methods.
-- Retrieve posts, pages, custom post types, categories, tags, and other WordPress entities.
-- Create, update, and delete posts and pages.
-- Upload media files to WordPress media library.
+- Retrieve posts, pages, custom post types, categories, tags and other WordPress entities.
+- Create, update and delete posts and pages.
 - Perform advanced queries and filter responses using the power of the WordPress RESTful API.
+- Use the [APIClient](https://wprestclient.readthedocs.io/en/latest/usage/client) for low level calls
+- Use [Repositories](https://wprestclient.readthedocs.io/en/latest/usage/repositories) and gain WordPress entity objects
+- [Configurable API Prefix](https://wprestclient.readthedocs.io/en/latest/extending/api-prefix)
+- [Create custom entities](https://wprestclient.readthedocs.io/en/latest/extending/entity) or extend the existing ones
+- [Create custom repositories](https://wprestclient.readthedocs.io/en/latest/extending/repository) for any endpoint
 
 ## Requirements
 
@@ -55,13 +57,41 @@ composer require angelxmoreno/wprestclient
        echo $post->getTitle();
    }
     ```
+
+4. Create a new Page via the `PagesRepository` using the `RepositoryRegistry`:
+   By creating an instance of `RepositoryRegistry`, you have access to all the registered repositories with
+   the `ApiClient` already set.
+
+    ```php
+   use WPRestClient\Repository\PagesRepository;
+   use WPRestClient\Core\RepositoryRegistry;
+   use WPRestClient\Entity\PageEntity;
+
+   $registry = new RepositoryRegistry($client);
+   $page = new PageEntity(['title' => 'A New Page']);
+   $registry->pages()->create($page);
+    ```   
+
+5. Delete a post via the `PostsRepository` using the `RepositoryRegistry`:
+
+    ```php
+   use WPRestClient\Repository\PagesRepository;
+   use WPRestClient\Core\RepositoryRegistry;
+   use WPRestClient\Entity\PageEntity;
 
-For more detailed usage examples and available methods, please refer to the documentation coming soon.
+   $registry = new RepositoryRegistry($client);
+   $post = $registry->posts()->get(123);
+   $registry->posts()->delete($post);
+    ```
+
+For more detailed usage examples and available methods, please refer to
+the [documentation](https://wprestclient.readthedocs.io/en/latest/).
 
 ## Contribution
 
 Contributions are welcome! If you find a bug, have suggestions for improvements, or would like to add new features,
-please submit an issue or a pull request. Make sure to follow our [contribution guidelines](CONTRIBUTION_GUIDELINES.md)
+please submit an issue or a pull request. Make sure to follow
+our [contribution guidelines](https://wprestclient.readthedocs.io/en/latest/contributing/)
 
 ## License
 

diff --git a/docs/code_of_conduct.md b/docs/code_of_conduct.md
@@ -0,0 +1,34 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of the WPRestClient project, we pledge to follow the guidelines outlined in this code of
+conduct to ensure a welcoming and inclusive environment for everyone. We value the participation of all contributors and
+aim to foster a positive and respectful community.
+
+## Guidelines
+
+1. **Be Respectful:** Treat all individuals with respect and kindness, regardless of their background, experience level,
+   or opinions.
+2. **Embrace Diversity:** Embrace and celebrate diversity in all forms, including but not limited to race, ethnicity,
+   nationality, gender identity, sexual orientation, religion, age, and abilities.
+3. **Open Communication:** Encourage open and constructive communication. Listen attentively and be considerate of
+   others' ideas and perspectives.
+4. **Constructive Feedback:** Provide feedback in a constructive and respectful manner. Focus on the issue at hand and
+   avoid personal attacks or derogatory language.
+5. **No Harassment:** Harassment, trolling, or any form of disrespectful or offensive behavior will not be tolerated.
+   This includes, but is not limited to, offensive comments, sexual advances, and any other behavior that creates an
+   unsafe or uncomfortable environment.
+6. **Respect Privacy:** Respect the privacy and confidentiality of others. Do not share personal information without
+   explicit consent.
+7. **Collaboration and Cooperation:** Strive for collaboration and cooperation among contributors. Help each other,
+   share knowledge, and support fellow contributors.
+
+## Reporting Issues
+
+If you encounter any violations of this code of conduct or witness behavior that goes against the principles outlined
+here, please report it to the project maintainers at [WPRestClient@gmail.com](mailto:WPRestClient@gmail.com). All
+reports will be reviewed and treated with strict confidentiality. We are committed to maintaining a positive community
+and will take appropriate action to address any issues.
+
+By participating in the WPRestClient project, you are expected to adhere to this code of conduct throughout all
+interactions and engagements within the project community. This code of conduct is adapted from the Contributor Covenant
+(version 2.0), available at [https://www.contributor-covenant.org/version/2/0/code_of_conduct.html].
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1,59 @@
+# Contribution Guidelines
+
+We welcome and appreciate contributions to the WPRestClient project. To ensure a smooth and collaborative process,
+please take a moment to review the following guidelines.
+
+## Code of Conduct
+
+Please familiarize yourself with our [Code of Conduct](code_of_conduct.md) to understand the expected behavior and
+conduct within our project community.
+
+## Ways to Contribute
+
+There are several ways you can contribute to WPRestClient:
+
+1. **Reporting Issues:** If you come across any bugs, issues, or have feature requests, please open an issue on
+   our [GitHub repository](https://github.com/angelxmoreno/WPRestClient/issues) and provide a detailed description.
+
+2. **Bug Fixes and Enhancements:** You can contribute by fixing bugs or enhancing existing features. Fork the
+   repository, make your changes in a new branch, and submit a pull request.
+
+3. **Documentation:** Improvements to documentation are highly appreciated. If you notice any areas that need
+   clarification or have suggestions for better explanations, feel free to submit a pull request.
+
+4. **Testing:** Help improve the reliability and stability of the library by writing and running tests. Contributions
+   that include new test cases or improve test coverage are valuable.
+
+## Getting Started
+
+1. Fork the repository to your GitHub account.
+2. Clone the forked repository to your local development environment.
+3. Install the project dependencies by running the following command:
+
+   ```bash
+   composer install
+   ```
+4. Make your changes, additions, or fixes in a new branch, ensuring clear and concise commit messages.
+5. Test your changes thoroughly to ensure they don't introduce new issues.
+6. Push your changes to your forked repository.
+7. Submit a pull request to the `main` branch of the WPRestClient repository. Provide a detailed description of your
+   changes and the problem they solve.
+
+## Pull Request Guidelines
+
+- Follow the coding style and conventions used in the project.
+- Provide a clear and descriptive title for your pull request.
+- Include a detailed description of the changes and the problem they address.
+- Reference any related issues or pull requests in your description using the appropriate GitHub syntax (e.g., "#123").
+- Ensure your code passes all existing tests, and if applicable, include new tests for your changes.
+- Be responsive to feedback and comments during the review process.
+
+## License
+
+By contributing to WPRestClient, you agree that your contributions will be licensed under the [MIT License](LICENSE).
+
+We appreciate your valuable contributions to the project! Thank you for helping us improve WPRestClient and make it
+even better.
+
+If you have any questions or need further assistance, feel free to reach out to
+[WPRestClient@gmail.com](mailto:WPRestClient@gmail.com)
diff --git a/docs/extending/api-prefix.md b/docs/extending/api-prefix.md
@@ -0,0 +1,4 @@
+# Changing the API Prefix
+
+Once you have an instance of `ApiClient` you can use the `setApiPrefix()` method override the default prefix
+of `wp-json/wp/v2`. See [Api Prefix](../usage/client.md#api-prefix) for more info.
diff --git a/docs/extending/authentication.md b/docs/extending/authentication.md
@@ -0,0 +1,27 @@
+# Creating a Custom Authentication
+
+Authentication classes are simple to create. They must implement the `AuthInterface` interface and implement
+the `withAuth()` method. This method takes in an instance of a Psr RequestInterface generated by the `ApiClient`.
+Authentication
+classes simply return an augmented request object for the `ApiClient` to send over the wire.
+
+Below is an example of how to create an authentication class that adds a JWT to the request:
+
+```php
+use WPRestClient\Core\AuthInterface;
+use Psr\Http\Message\RequestInterface;
+
+class JwtAuthentication implements AuthInterface 
+{
+    protected string $jwt;
+
+    public function __construct(string $jwt) {
+        $this->jwt = $jwt;
+    }
+
+    public function withAuth(RequestInterface $request): RequestInterface
+    {
+        return $request->withAddedHeader('Authorization', 'Bearer ' . $this->jwt);
+    }
+}
+```
diff --git a/docs/extending/entity.md b/docs/extending/entity.md
@@ -0,0 +1,3 @@
+# Creating a Custom Entity
+
+TBA
diff --git a/docs/extending/repository.md b/docs/extending/repository.md
@@ -0,0 +1,3 @@
+# Creating a Custom Repository
+
+TBA
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,35 @@
+# WPRestClient
+
+a PHP WordPress API Client
+
+WPRestClient is a PHP library for seamless interaction with WordPress sites via the WordPress RESTful API, simplifying
+authentication, data retrieval, and content management tasks
+
+## Features
+
+- Connect to WordPress sites and authenticate using REST API authentication methods.
+- Retrieve posts, pages, custom post types, categories, tags and other WordPress entities.
+- Create, update and delete posts and pages.
+- Perform advanced queries and filter responses using the power of the WordPress RESTful API.
+- Use the [APIClient](usage/client.md) for low level calls
+- Use [Repositories](usage/repositories.md) and gain WordPress entity objects
+- [Configurable API Prefix](extending/api-prefix.md)
+- [Create custom entities](extending/entity.md) or extend the existing ones
+- [Create custom repositories](extending/repository.md) for any endpoint
+
+## Installation
+
+View our [Installation instructions](installation.md)
+
+## Quickstart
+
+Get started by following along our [Quickstart Guide](quickstart.md)
+
+## Usage Examples
+
+- [Using Repositories](usage/repositories.md)
+- [Using the API Client](usage/client.md)
+
+## Contributing
+
+Follow our [Contribution Guidelines](contributing.md)
diff --git a/docs/installation.md b/docs/installation.md
@@ -0,0 +1,11 @@
+# Installation
+
+You can install WPRestClient via Composer. Run the following command in your project directory:
+
+```bash
+composer require angelxmoreno/wprestclient
+```
+
+### Next
+
+Follow along our [quickstart guide](quickstart.md)