From 62d77f916592f210bd109946e8d40725d1616f46 Mon Sep 17 00:00:00 2001 From: Constantin Ross Date: Fri, 1 Nov 2024 12:04:49 +0100 Subject: [PATCH 1/8] feat (docs): add contributing guidelines --- CONTRIBUTING.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..1d762c10 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,53 @@ +# Contributing + +This package is primarily maintained by the community. External contributions are always welcome. If you need assistance, feel free to [open an issue](https://github.com/prismicio-community/php-kit/issues/new/choose) or request a review by opening a pull request. + +## Setup + +To get started working on this project, you’ll need the following set up on your local machine: + +- PHP 8.0+ +- Composer 2.0+ +- The [APCu](https://www.php.net/manual/en/ref.apcu.php) extension for PHP + +Clone this GitHub repository, then run the following command to install all dependencies: + +```bash +$ composer install +``` + +## Project-specific Notes + +Some of the SDK’s tests require APCu (Alternative PHP Cache) to function correctly from the command line. If you have APC installed and enabled, but cache-related tests still fail, please try the following: + +- **Verify APC is enabled for CLI:** Run `php -i | grep apc` to check if APC is active for the command line. If no output appears, APC may be enabled only for the web server (e.g., Apache) and not for CLI. Consult your OS documentation to enable APC for CLI. If it involves modifying a `php.ini` file, ensure you're editing the correct one, as there may be separate `php.ini` files for the web server and CLI. + +- **Enable the `apc.enable_cli` setting:** If APC is enabled for CLI but tests still fail, verify that `apc.enable_cli` is set to ‘On’ in the output of `php -i | grep apc`. If it isn’t, add `apc.enable_cli = 1` at the end of the appropriate `php.ini` file. Again, confirm you are editing the correct `php.ini` file for CLI, not the one used by Apache. + +## Develop + +Once your environment is set up, you can start developing new features or fixing bugs. Please ensure that you follow the coding standards and conventions in the existing codebase. + +Before starting on a large change, it’s recommended that you open an issue to discuss your proposed changes. This allows you to receive early feedback and helps determine the best way to proceed. + +## Tests + +Please ensure that you write tests for any new features or bug fixes you implement. + +If you find existing code that could benefit from additional testing, we appreciate contributions to improve test coverage. In such cases, please create a dedicated branch and submit a separate pull request to document and review your testing improvements. + +You can run the tests with the following command: + +```bash +$ ./vendor/bin/phpunit +``` + +## Submit a pull request + +When you are ready to submit your changes, push your branch to the repository and open a pull request. Please include a detailed description of your changes and any relevant information for reviewers. + +Your pull request will be reviewed by a maintainer. If changes are requested, please make them on your branch and push the updates to the repository. The pull request will be updated automatically. + +## Publish + +Publishing a new version of the package is restricted to maintainers. From b5051cadcb635c5a1788d931445173ecb436a52b Mon Sep 17 00:00:00 2001 From: Constantin Ross Date: Fri, 1 Nov 2024 12:08:26 +0100 Subject: [PATCH 2/8] feat (contrib): add issue templates to github --- .github/ISSUE_TEMPALTE/bug_report.md | 28 +++++++++++++++++++++++ .github/ISSUE_TEMPALTE/config.yml | 1 + .github/ISSUE_TEMPALTE/feature_request.md | 23 +++++++++++++++++++ .github/ISSUE_TEMPALTE/question.md | 11 +++++++++ 4 files changed, 63 insertions(+) create mode 100644 .github/ISSUE_TEMPALTE/bug_report.md create mode 100644 .github/ISSUE_TEMPALTE/config.yml create mode 100644 .github/ISSUE_TEMPALTE/feature_request.md create mode 100644 .github/ISSUE_TEMPALTE/question.md diff --git a/.github/ISSUE_TEMPALTE/bug_report.md b/.github/ISSUE_TEMPALTE/bug_report.md new file mode 100644 index 00000000..24981d3b --- /dev/null +++ b/.github/ISSUE_TEMPALTE/bug_report.md @@ -0,0 +1,28 @@ +--- +name: 🚨 Bug report +about: Report a bug to help improve the package. +title: "" +labels: "bug" +assignees: "" +--- + +### Versions + +- @prismic/sdk: +- php: + +### Reproduction + + + +### Steps to reproduce + + + +### What is expected? + + + +### What is actually happening? + + diff --git a/.github/ISSUE_TEMPALTE/config.yml b/.github/ISSUE_TEMPALTE/config.yml new file mode 100644 index 00000000..3ba13e0c --- /dev/null +++ b/.github/ISSUE_TEMPALTE/config.yml @@ -0,0 +1 @@ +blank_issues_enabled: false diff --git a/.github/ISSUE_TEMPALTE/feature_request.md b/.github/ISSUE_TEMPALTE/feature_request.md new file mode 100644 index 00000000..8d59e334 --- /dev/null +++ b/.github/ISSUE_TEMPALTE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: 🙋‍♀️ Feature request +about: Suggest an idea or enhancement for the package. +title: "" +labels: "enhancement" +assignees: "" +--- + +### Is your feature request related to a problem? Please describe. + + + +### Describe the solution you'd like + + + +### Describe alternatives you've considered + + + +### Additional context + + diff --git a/.github/ISSUE_TEMPALTE/question.md b/.github/ISSUE_TEMPALTE/question.md new file mode 100644 index 00000000..08ced81b --- /dev/null +++ b/.github/ISSUE_TEMPALTE/question.md @@ -0,0 +1,11 @@ +--- +name: ❔Question +about: Ask a question about the package or any of its features. +title: "" +labels: "question" +assignees: "" +--- + +### Question + + From 568e5c304da9c0677166d9f7490beddaba09e07a Mon Sep 17 00:00:00 2001 From: Constantin Ross Date: Fri, 1 Nov 2024 12:08:55 +0100 Subject: [PATCH 3/8] chore (license): update the license --- LICENSE | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/LICENSE b/LICENSE index d823fe49..1b88dbc8 100644 --- a/LICENSE +++ b/LICENSE @@ -1,5 +1,13 @@ -Copyright 2018 Prismic (https://prismic.io). +Copyright 2013-2024 Prismic (https://prismic.io) -Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at -Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. From e2b3dc75a4373d6c98678761d25a9b941a79a8fe Mon Sep 17 00:00:00 2001 From: Constantin Ross Date: Fri, 1 Nov 2024 12:11:27 +0100 Subject: [PATCH 4/8] feat (docs): improve readme --- README.md | 109 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 69 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index e217a431..69d03ed7 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,43 @@ +# Prismic.io PHP SDK + [![Github Actions CI][github-actions-ci-src]][github-actions-ci-href] +[![Total Downloads][packagist-downloads-src]][packagist-downloads-href] +[![Latest Stable Version][packagist-version-src]][packagist-version-href] +[![License][packagist-license-src]][packagist-license-href] + +This is the official PHP SDK for Prismic.io, providing a straightforward way to connect to Prismic’s headless API. It is maintained by the community to help developers get started with Prismic in PHP. + +- Offers an easy-to-use interface for basic interactions with Prismic content +- Covers core features of the Prismic API + +### Overview -# PHP development kit for Prismic +1. [Getting started](#getting-started) + 1. [Requirements](#requirements) + 2. [Installation](#installation) + 3. [Basic Usage & API calls](#basic-usage--api-calls) + 4. [DOM Helper](#dom-helper) +2. [More information](#more-information) +3. [Contributing](#contributing) +4. [License](#license) ## Getting started -### Install the kit for your project +### Requirements -First of all, install [APCu](https://www.php.net/manual/en/ref.apcu.php) to have the default built-in cache support. +If you want to have the built-in default cache support, you need to have the [APCu](https://www.php.net/manual/en/ref.apcu.php) extension installed and enabled. -Install with [Composer](https://getcomposer.org/doc/00-intro.md): +### Installation + +Installation using [Composer](https://getcomposer.org/doc/00-intro.md): ```bash $ composer require prismic/php-sdk ``` -### Usage +### Basic Usage & API calls -Include the dependency: +If you are not using automatic autoloading, include the Composer autoload file: ```php getByUID('get-started-type', 'get-started'); +$document = $api->getByUID('get-started-type', 'get-started'); ``` -This kit supports PHP version >= 8.0 +### DOM Helper -### DOM helpers usage +The PHP SDK provides a set of DOM helpers to help you render your Prismic content. -In these examples we have a $doc variable corresponding to the fetched Prismic document. -We also have a $linkResolver variable containing the functional link resolver, [read our docs to learn more about Link Resolving](https://prismic.io/docs/php/beyond-the-api/link-resolving). +In these examples we have a document variable corresponding to the fetched Prismic document. We also have a $linkResolver variable containing the functional link resolver, [read our docs to learn more about Link Resolving](https://prismic.io/docs/php/beyond-the-api/link-resolving). #### Link @@ -46,7 +65,7 @@ We also have a $linkResolver variable containing the functional link resolver, [ data->link, $linkResolver); +echo Link::asUrl($document->data->link, $linkResolver); ``` #### Rich Text @@ -55,8 +74,8 @@ echo Link::asUrl($doc->data->link, $linkResolver); data->title); -echo RichText::asHtml($doc->data->description, $linkResolver); +echo RichText::asText($document->data->title); +echo RichText::asHtml($document->data->description, $linkResolver); ``` #### Date @@ -65,51 +84,61 @@ echo RichText::asHtml($doc->data->description, $linkResolver); data->date); +$date = Date::asDate($document->data->date); echo $date->format('Y-m-d H:i:s'); ``` ## More information -- [Developer docs](./docs) -- [PHP Quickstart tutorial](https://prismic.io/quickstart#?lang=php) -- [PHPDoc](https://prismicio-community.github.io/php-kit/) +- [Developer Documentaiton](./docs) +- [Generated PHPDoc](https://prismicio-community.github.io/php-kit/) - [Changelog](https://github.com/prismicio-community/php-kit/releases) -## Install the kit locally +## Contributing -Clone this GitHub repository, then [install Composer](https://getcomposer.org/doc/00-intro.md) if you haven't, and run: +Whether you're helping us fix bugs, improve the docs, or spread the word, we'd love to have you as part of the Prismic developer community! -```bash -$ composer install -``` +**Reporting a bug**: [Open an issue][repo-bug-report] explaining your application's setup and the bug you're encountering. -## Tests +**Suggesting an improvement**: [Open an issue][repo-feature-request] explaining your improvement or feature so we can discuss and learn more. -Please write tests for any bugfix or new feature. +**Submitting code changes**: For small fixes, feel free to [open a pull request][repo-pull-requests] with a description of your changes. For large changes, please first [open an issue][repo-feature-request] so we can discuss if and how the changes should be implemented. -If you find existing code that is not optimally tested and wish to make it better, we really appreciate it; but you should document it on its own branch and its own pull request. +For more clarity on this project, check out the detailed [CONTRIBUTING.md](./CONTRIBUTING.md) for our guidelines. -Tests are run by running the command: +## License -```bash -$ ./vendor/bin/phpunit -``` +This software is licensed under the [Apache 2 License](https://opensource.org/license/apache-2-0), quoted below: -Some of the kit's tests check stuff that are built on top of APC and need APC to work from the command line. If you've installed and enabled APC, and your cache tests don't pass: +```plaintext +Copyright 2013-2024 Prismic (https://prismic.io) -- check if your APC is enabled for your command line, by running `php -i | grep apc`; if no output is displayed, then maybe the APC extension you installed and enabled is only enabled in apache but not for your command line. Check how your OS works to make that happen, and if it involves changing a php.ini file, make sure it's the right php.ini (you might have one for apache, and one for the command line) -- if APC is enabled for the command line, and yet the tests still fail, make sure your `apc.enable_cli` (which you see in the output of `php -i | grep apc`) is 'On'. If it's not, add this at the end of your php.ini: `apc.enable_cli = 1`. Make sure it's the right php.ini (you might have one for apache, and one for the command line) +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at -## License + http://www.apache.org/licenses/LICENSE-2.0 -This software is licensed under the Apache 2 license, quoted below. +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +``` -Copyright 2018 Prismic (https://prismic.io). + -Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. +[repo-bug-report]: https://github.com/prismicio-community/php-kit/issues/new?assignees=&labels=bug&template=bug_report.md&title= +[repo-feature-request]: https://github.com/prismicio-community/php-kit/issues/new?assignees=&labels=enhancement&template=feature_request.md&title= +[repo-pull-requests]: https://github.com/prismicio-community/php-kit/pulls -Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. + [github-actions-ci-src]: https://github.com/prismicio-community/php-kit/workflows/ci/badge.svg [github-actions-ci-href]: https://github.com/prismicio-community/php-kit/actions?query=workflow%3Aci +[packagist-downloads-src]: https://img.shields.io/packagist/dm/prismic/php-sdk +[packagist-downloads-href]: https://packagist.org/packages/prismicio-community/php-kit +[packagist-version-src]: https://img.shields.io/packagist/v/prismic/php-sdk +[packagist-version-href]: https://packagist.org/packages/prismicio-community/php-kit +[packagist-license-src]: https://img.shields.io/packagist/l/prismic/php-sdk +[packagist-license-href]: https://packagist.org/packages/prismicio-community/php-kit From 368952feafc6fcc8493e72faac90e5b011532e82 Mon Sep 17 00:00:00 2001 From: Constantin Ross Date: Tue, 5 Nov 2024 17:57:38 +0100 Subject: [PATCH 5/8] chore (contrib): drop question issue template for link to discussions tab --- .github/ISSUE_TEMPALTE/config.yml | 4 ++++ .github/ISSUE_TEMPALTE/question.md | 11 ----------- 2 files changed, 4 insertions(+), 11 deletions(-) delete mode 100644 .github/ISSUE_TEMPALTE/question.md diff --git a/.github/ISSUE_TEMPALTE/config.yml b/.github/ISSUE_TEMPALTE/config.yml index 3ba13e0c..5445fa02 100644 --- a/.github/ISSUE_TEMPALTE/config.yml +++ b/.github/ISSUE_TEMPALTE/config.yml @@ -1 +1,5 @@ blank_issues_enabled: false +contact_links: + - name: GitHub Discussions + url: https://github.com/prismicio-community/php-kit/discussions/new/choose + about: Ask a question about the package or raise an issue directly related the the package. diff --git a/.github/ISSUE_TEMPALTE/question.md b/.github/ISSUE_TEMPALTE/question.md deleted file mode 100644 index 08ced81b..00000000 --- a/.github/ISSUE_TEMPALTE/question.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: ❔Question -about: Ask a question about the package or any of its features. -title: "" -labels: "question" -assignees: "" ---- - -### Question - - From 5545af6abf71d6d3287f33dae364031c39b78219 Mon Sep 17 00:00:00 2001 From: Constantin Ross Date: Tue, 5 Nov 2024 18:09:31 +0100 Subject: [PATCH 6/8] feat (docs): improve readme --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 69d03ed7..fefc6888 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,8 @@ This is the official PHP SDK for Prismic.io, providing a straightforward way to ### Overview 1. [Getting started](#getting-started) - 1. [Requirements](#requirements) - 2. [Installation](#installation) + 1. [Installation](#installation) + 2. [Reccomended PHP Extension](#reccomended-php-extensions) 3. [Basic Usage & API calls](#basic-usage--api-calls) 4. [DOM Helper](#dom-helper) 2. [More information](#more-information) @@ -23,10 +23,6 @@ This is the official PHP SDK for Prismic.io, providing a straightforward way to ## Getting started -### Requirements - -If you want to have the built-in default cache support, you need to have the [APCu](https://www.php.net/manual/en/ref.apcu.php) extension installed and enabled. - ### Installation Installation using [Composer](https://getcomposer.org/doc/00-intro.md): @@ -35,6 +31,10 @@ Installation using [Composer](https://getcomposer.org/doc/00-intro.md): $ composer require prismic/php-sdk ``` +### Reccomended PHP Extensions + +We recommend installing and enabeling the [APCu](https://www.php.net/manual/en/ref.apcu.php) extension to have the built-in default cache support. Otherwise, you can implement your own cache strategy by extending the `Prismic\Cache\CacheInterface` interface. + ### Basic Usage & API calls If you are not using automatic autoloading, include the Composer autoload file: From 76f88b76636e3184981e64b86db5d2d3f814fc32 Mon Sep 17 00:00:00 2001 From: Constantin Ross Date: Tue, 5 Nov 2024 18:10:59 +0100 Subject: [PATCH 7/8] chore (docs): fix typo in improved readme --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fefc6888..c43fd9b1 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ This is the official PHP SDK for Prismic.io, providing a straightforward way to 1. [Getting started](#getting-started) 1. [Installation](#installation) - 2. [Reccomended PHP Extension](#reccomended-php-extensions) + 2. [Recommended PHP Extensions](#recommended-php-extensions) 3. [Basic Usage & API calls](#basic-usage--api-calls) 4. [DOM Helper](#dom-helper) 2. [More information](#more-information) @@ -31,7 +31,7 @@ Installation using [Composer](https://getcomposer.org/doc/00-intro.md): $ composer require prismic/php-sdk ``` -### Reccomended PHP Extensions +### Recommended PHP Extensions We recommend installing and enabeling the [APCu](https://www.php.net/manual/en/ref.apcu.php) extension to have the built-in default cache support. Otherwise, you can implement your own cache strategy by extending the `Prismic\Cache\CacheInterface` interface. From e98e679115ccc915527dfaf74034ca7973635843 Mon Sep 17 00:00:00 2001 From: Constantin Ross Date: Tue, 5 Nov 2024 18:28:01 +0100 Subject: [PATCH 8/8] chore (docs): improve contributing guidelines --- CONTRIBUTING.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d762c10..486fd0f2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -30,6 +30,17 @@ Once your environment is set up, you can start developing new features or fixing Before starting on a large change, it’s recommended that you open an issue to discuss your proposed changes. This allows you to receive early feedback and helps determine the best way to proceed. +If you want to test your changes in an example you can either create a new file in the `samples` directory or modify an existing one (locally). In case you want to test the changes in a real project, you can link your local package to the project using [Composer](https://getcomposer.org/doc/05-repositories.md#path). + +In any case please make sure to write test cases for your changes. + +**Useful commands:** + +| Command | Description | +| ------------------- | -------------------------------------------------------------------------------- | +| `composer test` | This command will run the test suite with PHPUnit (requires the APCu extension). | +| `composer cs-check` | This command will check the code style with PHP CS Fixer. | + ## Tests Please ensure that you write tests for any new features or bug fixes you implement.