This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
The following commit(s) were added to refs/heads/main by this push:
new dac7910fe docs: improve php binding documentation (#2843)
dac7910fe is described below
commit dac7910fe7d063033d6f7da19eeefa38437c0365
Author: Lianbo <[email protected]>
AuthorDate: Fri Aug 11 12:21:44 2023 +0800
docs: improve php binding documentation (#2843)
* docs: improve php documentation
* docs: test
* docs: test
---
bindings/php/README.md | 70 ++++++++++++++++++++++++++++++++++++++++++--------
1 file changed, 60 insertions(+), 10 deletions(-)
diff --git a/bindings/php/README.md b/bindings/php/README.md
index 1c04c8629..5013fa89e 100644
--- a/bindings/php/README.md
+++ b/bindings/php/README.md
@@ -1,32 +1,82 @@
-# OpenDAL PHP Binding (WIP)
+# OpenDAL PHP Binding
+
+## Example
+
+```php
+use OpenDAL\Operator;
+
+$op = new Operator("fs", ["root" => "/tmp"]);
+$op->write("test.txt", "hello world");
+
+echo $op->read("test.txt"); // hello world
+```
## Requirements
* PHP 8.1+
+* Composer
-## Development
+## Install Extension
-### Install Cargo PHP
+We use [ext-php-rs](https://github.com/davidcole1340/ext-php-rs) to build PHP
extensions natively in Rust, it's different from the traditional PHP extension
development and cannot be installed using `pecl` or `phpize`. Before installing
the extension, it is necessary to install Rust and Cargo. For instructions on
how to install them, please refer to [Rust's
website](https://www.rust-lang.org/tools/install).
-we use
[cargo-php](https://davidcole1340.github.io/ext-php-rs/getting-started/hello_world.html)
to build the PHP extension.
+1. Clone the repository
```bash
-cargo install cargo-php
+git clone [email protected]:apache/incubator-opendal.git
```
-### Build
-
-Move to the `bindings/php` directory and run the following command, the
extension will be built in `target/debug` directory and enable the extension in
`php.ini` file.
+2. Build the opendal-php extension
```bash
+cd incubator-opendal/bindings/php
cargo build
+```
+
+> don't forget to add `--release` flag for production use.
+
+3. Enable extension for PHP Manually
+
+```bash
+cd incubator-opendal
+
+# Linux
+cp target/debug/libopendal_php.so $(php -r "echo
ini_get('extension_dir');")/libopendal_php.so
+echo "extension=libopendal_php.so" >> $(php -r "echo php_ini_loaded_file();")
+
+# macOS
+cp target/debug/libopendal_php.dylib $(php -r "echo
ini_get('extension_dir');")/libopendal_php.dylib
+echo "extension=libopendal_php.dylib" >> $(php -r "echo
php_ini_loaded_file();")
+
+# Windows
+cp target/debug/libopendal_php.dll $(php -r "echo
ini_get('extension_dir');")/libopendal_php.dll
+echo "extension=libopendal_php.dll" >> $(php -r "echo php_ini_loaded_file();")
+```
+
+4. Enable extension for PHP using cargo-php
+
+You can also use cargo-php directly to install the extension, see
[cargo-php](https://davidcole1340.github.io/ext-php-rs/getting-started/cargo-php.html)
for more details.
+
+```bash
+cargo install cargo-php
+cd incubator-opendal/bindings/php
cargo php install
```
+This command will automatically build the extension and copy it to the
extension directory of the current PHP version.
-### Test
+5. Test
+
+use `php -m` to check if the extension is installed successfully.
```bash
+php -m | grep opendal-php
+```
+
+Composer test:
+
+```bash
+cd incubator-opendal/bindings/php
+
composer install
composer test
```
-
