Skip to content

Commit

Permalink
chore: update README for web site inclusion
Browse files Browse the repository at this point in the history 
Signed-off-by: Todd Baert <[email protected]>
  • Loading branch information
@toddbaert
toddbaert committed Oct 26, 2023
1 parent f84ecdd commit 74f73a3
Show file tree
Hide file tree
Showing 2 changed files with 230 additions and 46 deletions.
219 changes: 174 additions & 45 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,32 +1,88 @@
# OpenFeature SDK for PHP
<!-- markdownlint-disable MD033 -->
<!-- x-hide-in-docs-start -->
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/open-feature/community/0e23508c163a6a1ac8c0ced3e4bd78faafe627c7/assets/logo/horizontal/white/openfeature-horizontal-white.svg" />
<img align="center" alt="OpenFeature Logo" src="https://raw.githubusercontent.com/open-feature/community/0e23508c163a6a1ac8c0ced3e4bd78faafe627c7/assets/logo/horizontal/black/openfeature-horizontal-black.svg" />
</picture>
</p>

[![a](https://img.shields.io/badge/slack-%40cncf%2Fopenfeature-brightgreen?style=flat&logo=slack)](https://cloud-native.slack.com/archives/C0344AANLA1)
[![codecov](https://codecov.io/gh/open-feature/php-sdk/branch/main/graph/badge.svg?token=3DC5XOEHMY)](https://codecov.io/gh/open-feature/php-sdk)
[![Specification](https://img.shields.io/static/v1?label=Specification&message=v0.5.1&color=yellow)](https://github.com/open-feature/spec/tree/v0.5.1)
[![Latest Stable Version](http://poser.pugx.org/open-feature/sdk/v)](https://packagist.org/packages/open-feature/sdk)
[![Total Downloads](http://poser.pugx.org/open-feature/sdk/downloads)](https://packagist.org/packages/open-feature/sdk)
![PHP 8.0+](https://img.shields.io/badge/php->=8.0-blue.svg)
[![License](http://poser.pugx.org/open-feature/sdk/license)](https://packagist.org/packages/open-feature/sdk)
[![OpenSSF Best Practices](https://bestpractices.coreinfrastructure.org/projects/6853/badge)](https://bestpractices.coreinfrastructure.org/projects/6853)
<h2 align="center">OpenFeature PHP SDK</h2>

## Overview
<!-- x-hide-in-docs-end -->
<!-- The 'github-badges' class is used in the docs -->
<p align="center" class="github-badges">

This package provides a functional SDK for an OpenFeature API and client. It also builds on various PSRs (PHP Standards Recommendations) such as the Logger interfaces (PSR-3) and the Basic and Extended Coding Standards (PSR-1 and PSR-12).
<a href="https://github.com/open-feature/spec/releases/tag/v0.5.1">
<img alt="Specification" src="https://img.shields.io/static/v1?label=specification&message=v0.5.1&color=yellow&style=for-the-badge" />
</a>
<!-- x-release-please-start-version -->

Future development goals for the package include:
<a href="https://github.com/open-feature/my-sdk/releases/tag/v0.0.1">
<img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.3.1&color=blue&style=for-the-badge" />
</a>

- Integrate container standards (PSR-11)
- Build on PHP HTTP Promises to support async clients
<!-- x-release-please-end -->
<br/>

## Installation
<a href="https://packagist.org/packages/open-feature/sdk">
<img alt="Total Downloads" src="https://poser.pugx.org/open-feature/sdk/downloads" />
</a>

<a>
<img alt="PHP 8.0+" src="https://img.shields.io/badge/php->=8.0-blue.svg" />
</a>

<a href="https://packagist.org/packages/open-feature/sdk">
<img alt="License" src="https://poser.pugx.org/open-feature/sdk/license" />
</a>

<a href="https://bestpractices.coreinfrastructure.org/projects/6853">
<img alt="OpenSSF Best Practices" src="https://bestpractices.coreinfrastructure.org/projects/6853/badge" />
</a>

</p>
<!-- x-hide-in-docs-start -->

[OpenFeature](https://openfeature.dev) is an open standard that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool.

<!-- x-hide-in-docs-end -->
## 🚀 Quick start

### Requirements

This library targets PHP version 8.0 and newer. As long as you have any compatible version of PHP on your system you should be able to utilize the OpenFeature SDK.

This package also has a `.tool-versions` file for use with PHP version managers like `asdf`.

### Install

```shell
composer require open-feature/sdk
```

## Usage
### Usage

```php
use OpenFeature\OpenFeatureAPI;
use OpenFeature\Providers\Flagd\FlagdProvider;

function example()
{
$api = OpenFeatureAPI::getInstance();

// configure a provider
$api->setProvider($provider);

// create a client
$client = $api->getClient();

// get a bool flag value
$client->getBooleanValue('v2_enabled', false)
}
```

While `Boolean` provides the simplest introduction, we offer a variety of flag types.
#### Extended Example

```php
use OpenFeature\OpenFeatureClient;
Expand Down Expand Up @@ -77,45 +133,118 @@ class MyClass
}
```

### Configuration
### API Reference

To configure OpenFeature, you'll need to add a provider to the global singleton `OpenFeatureAPI`. From there, you can generate a `Client` which is usable by your code. If you do not set a provider, then the `NoOpProvider`, which simply returns the default passed in, will be used.
<!-- TODO: link to formal API docs (ie: Javadoc) if available -->

```php
use OpenFeature\OpenFeatureAPI;
use OpenFeature\Providers\Flagd\FlagdProvider;
## 🌟 Features

class MyApp
{
public function bootstrap()
{
$api = OpenFeatureAPI::getInstance();
$api->setProvider(new FlagdProvider());
$client = $api->getClient();

// Now use your `$client` instance to evaluate some feature flags!
}
}
```
| Status | Features | Description |
| ------ | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| ✅ | [Providers](#providers) | Integrate with a commercial, open source, or in-house feature management tool. |
| ✅ | [Targeting](#targeting) | Contextually-aware flag evaluation using [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context). |
| ✅ | [Hooks](#hooks) | Add functionality to various stages of the flag evaluation life-cycle. |
| ❌ | [Logging](#logging) | Integrate with popular logging packages. |
| ❌ | [Named clients](#named-clients) | Utilize multiple providers in a single application. |
| ❌ | [Eventing](#eventing) | React to state changes in the provider or flag management system. |
| ❌ | [Shutdown](#shutdown) | Gracefully clean up a provider during application shutdown. |
| ✅ | [Extending](#extending) | Extend OpenFeature with custom providers and hooks. |

### Providers & Hooks
<sub>Implemented: ✅ | In-progress: ⚠️ | Not implemented yet: ❌</sub>

The OpenFeature project maintains the [open-feature/php-sdk-contrib](https://github.com/open-feature/php-sdk-contrib) repository, which includes contributed providers and hooks. Vendors can also implement and maintain their own providers as well. We update [the PHP docs page](https://openfeature.dev/docs/reference/technologies/server/php) with these vendors as often as possible.
### Providers

## Development
[Providers](https://openfeature.dev/docs/reference/concepts/provider) are an abstraction between a flag management system and the OpenFeature SDK.
Look [here](https://openfeature.dev/ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Provider&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=php) for a complete list of available providers.
If the provider you're looking for hasn't been created yet, see the [develop a provider](#develop-a-provider) section to learn how to build it yourself.

### PHP Versioning
Once you've added a provider as a dependency, it can be registered with OpenFeature like this:

This library targets PHP version 8.0 and newer. As long as you have any compatible version of PHP on your system you should be able to utilize the OpenFeature SDK.
<!-- TODO: code example setting a provider and setting it while awaiting init, if applicable -->

This package also has a `.tool-versions` file for use with PHP version managers like `asdf`.
In some situations, it may be beneficial to register multiple providers in the same application.
This is possible using [named clients](#named-clients), which is covered in more detail below.

### Targeting

Sometimes, the value of a flag must consider some dynamic criteria about the application or user, such as the user's location, IP, email address, or the server's location.
In OpenFeature, we refer to this as [targeting](https://openfeature.dev/specification/glossary#targeting).
If the flag management system you're using supports targeting, you can provide the input data using the [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context).

<!-- TODO: code examples using context and different levels -->


### Hooks

[Hooks](https://openfeature.dev/docs/reference/concepts/hooks) allow for custom logic to be added at well-defined points of the flag evaluation life-cycle.
Look [here](https://openfeature.dev/ecosystem/?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Hook&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=php) for a complete list of available hooks.
If the hook you're looking for hasn't been created yet, see the [develop a hook](#develop-a-hook) section to learn how to build it yourself.

Once you've added a hook as a dependency, it can be registered at the global, client, or flag invocation level.

<!-- TODO: code example of setting hooks at all levels -->

### Logging

Logging customization is not yet available in the PHP SDK.

### Named clients

Named clients are not yet available in the PHP SDK. Progress on this feature can be tracked [here](https://github.com/open-feature/php-sdk/issues/93).

### Eventing

Events are not yet available in the PHP SDK. Progress on this feature can be tracked [here](https://github.com/open-feature/php-sdk/issues/93).

### Shutdown

A shutdown method is not yet available in the PHP SDK. Progress on this feature can be tracked [here](https://github.com/open-feature/php-sdk/issues/93).

## Extending

### Develop a provider

To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency.
This can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/php-sdk-contrib) available under the OpenFeature organization.
You’ll then need to write the provider by implementing the `FeatureProvider` interface exported by the OpenFeature SDK.

<!-- TODO: code example of provider implementation -->

> Built a new provider? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=provider&projects=&template=document-provider.yaml&title=%5BProvider%5D%3A+) so we can add it to the docs!
### Develop a hook

To develop a hook, you need to create a new project and include the OpenFeature SDK as a dependency.
This can be a new repository or included in [the existing contrib repository](https://github.com/open-feature/php-sdk-contrib) available under the OpenFeature organization.
Implement your own hook by conforming to the `Hook interface`.
To satisfy the interface, all methods (`Before`/`After`/`Finally`/`Error`) need to be defined.
To avoid defining empty functions, make use of the `UnimplementedHook` struct (which already implements all the empty functions).

<!-- TODO: code example of hook implementation -->

> Built a new hook? [Let us know](https://github.com/open-feature/openfeature.dev/issues/new?assignees=&labels=hook&projects=&template=document-hook.yaml&title=%5BHook%5D%3A+) so we can add it to the docs!
<!-- x-hide-in-docs-start -->
## ⭐️ Support the project

- Give this repo a ⭐️!
- Follow us on social media:
- Twitter: [@openfeature](https://twitter.com/openfeature)
- LinkedIn: [OpenFeature](https://www.linkedin.com/company/openfeature/)
- Join us on [Slack](https://cloud-native.slack.com/archives/C0344AANLA1)
- For more, check out our [community page](https://openfeature.dev/community/)

## 🤝 Contributing

Interested in contributing? Great, we'd love your help! To get started, take a look at the [CONTRIBUTING](CONTRIBUTING.md) guide.

### Installation and Dependencies
### Thanks to everyone who has already contributed

Install dependencies with `composer install`. `composer install` will update the `composer.lock` with the most recent compatible versions.
<a href="https://github.com/open-feature/php-sdk/graphs/contributors">
<img src="https://contrib.rocks/image?repo=open-feature/php-sdk" alt="Pictures of the folks who have contributed to the project" />
</a>

We value having as few runtime dependencies as possible. The addition of any dependencies requires careful consideration and review.

### Testing

Run tests with `composer run test`.
Made with [contrib.rocks](https://contrib.rocks).
<!-- x-hide-in-docs-end -->
57 changes: 56 additions & 1 deletion release-please-config.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,62 @@
"prerelease": false,
"bump-minor-pre-major": true,
"bump-patch-for-minor-pre-major": true,
"include-v-in-tag": false
"include-v-in-tag": false,
"extra-files": ["README.md"],
"changelog-sections": [
{
"type": "fix",
"section": "🐛 Bug Fixes"
},
{
"type": "feat",
"section": "✨ New Features"
},
{
"type": "chore",
"section": "🧹 Chore"
},
{
"type": "docs",
"section": "📚 Documentation"
},
{
"type": "perf",
"section": "🚀 Performance"
},
{
"type": "build",
"hidden": true,
"section": "🛠️ Build"
},
{
"type": "deps",
"section": "📦 Dependencies"
},
{
"type": "ci",
"hidden": true,
"section": "🚦 CI"
},
{
"type": "refactor",
"section": "🔄 Refactoring"
},
{
"type": "revert",
"section": "🔙 Reverts"
},
{
"type": "style",
"hidden": true,
"section": "🎨 Styling"
},
{
"type": "test",
"hidden": true,
"section": "🧪 Tests"
}
]
}
}
}

0 comments on commit 74f73a3

Please sign in to comment.