Currently we only support throwing exception class entries, i.e. stateless exceptions. Ideally we also want to support throwing a ZVal which has a ClassEntry that extends the Exception PHP class. This can be used to throw stateful exceptions which is not uncommon.
This PR is missing one piece: `throw_object` will currently `drop` the Zval when the function is completed, causing reference / null pointer errors. It seems `ZVal::Drop` doesn't actually free the zval currently, it just sets the type to NULL (which also breaks things.) Discussed briefly in https://discord.com/channels/115233111977099271/1025314959179120714 on how best to solve this, but I'm not totally clear still! Ideally I think we want `throw_object` to own the `zval` but not free it once the function returns.
Closes https://github.com/davidcole1340/ext-php-rs/issues/208
Closes https://github.com/davidcole1340/ext-php-rs/issues/209
## Summary of the changes
### Build scripts
* the `unix_build.rs` script now honors the `PHP_CONFIG` environment variable, like `cargo php install`
* use `cargo:rerun-if-env-changed` for the `PHP`, `PHP_CONFIG` and `PATH` environment variables, to avoid needless recompilation of the whole dependency tree.
### Documentation
While trying to document the aforementioned changes, I realized that there was no chapter about installing and setting up a PHP environment to develop PHP extensions. So, I refactored the first chapters of the book into a `Getting Started` section, including instructions on how to quickly set up a PHP environment.
Closes https://github.com/davidcole1340/ext-php-rs/issues/200
## Rationale
In PHP zend_strings are binary strings with no encoding information. They can contain any byte at any position.
The current implementation use `CString` to transfer zend_strings between Rust and PHP, which prevents zend_strings containing null-bytes to roundtrip through the ffi layer. Moreover, `ZendStr::new()` accepts only a `&str`, which is incorrect since a zend_string is not required to be valid UTF8.
When reading the PHP source code, it is apparent that most functions marked with `ZEND_API` that accept a `const *char` are convenience wrappers that convert the `const *char` to a zend_string and delegate to another function. For example [zend_throw_exception()](eb83e0206c/Zend/zend_exceptions.c (L823)) takes a `const *char message`, and just converts it to a zend_string before delegating to [zend_throw_exception_zstr()](eb83e0206c/Zend/zend_exceptions.c (L795)).
I kept this PR focused around `ZendStr` and it's usages in the library, but it should be seen as the first step of a more global effort to remove usages of `CString` everywhere possible.
Also, I didn't change the return type of the string related methods of `Zval` (e.g. I could have made `Zval::set_string()`
accept an `impl AsRef<[u8]>` instead of `&str` and return `()` instead of `Result<()>`). If I get feedback that it should be done in this PR, I'll do it.
## Summary of the changes:
### ZendStr
* [BC break]: `ZendStr::new()` and `ZendStr::new_interned()` now accept an `impl AsRef<[u8]>` instead of just `&str`, and are therefore infaillible (outside of the cases where we panic, e.g. when allocation fails). This is a BC break, but it's impact shouldn't be huge (users will most likely just have to remove a bunch of `?` or add a few `Ok()`).
* [BC break]: Conversely, `ZendStr::as_c_str()` now returns a `Result<&CStr>` since it can fail on strings containing null bytes.
* [BC break]: `ZensStr::as_str()` now returns a `Result<&str>` instead of an `Option<&str>` since we have to return an error in case of invalid UTF8.
* adds method `ZendStr::as_bytes()` to return the underlying byte slice.
* adds convenience methods `ZendStr::as_ptr()` and `ZendStr::as_mut_ptr()` to return raw pointers to the zend_string.
### ZendStr conversion traits
* adds `impl AsRef<[u8]> for ZendStr`
* [BC break]: replaces `impl TryFrom<String> for ZBox<ZendStr>` by `impl From<String> for ZBox<ZendStr>`.
* [BC break]: replaces `impl TryFrom<&str> for ZBox<ZendStr>` by `impl From<&str> for ZBox<ZendStr>`.
* [BC break]: replaces `impl From<&ZendStr> for &CStr` by `impl TryFrom<&ZendStr> for &CStr`.
### Error
* adds new enum member `Error::InvalidUtf8` used when converting a `ZendStr` to `String` or `&str`
* adds `ZendObject::get_class_entry()` to retrieve the class entry of an object without casting pointers
* adds `ZendObject::instance_of()` to allow more idiomatic instanceof checks.
* adds a mention that `ZendObject::is_instance::<T>()` does not check the parent classes or interfaces. This bit me when I tried to check if `my_object.is_instance::<MyInterface>()` and it didn't work.
* upgrades LLVM to v14
* migrates from the unmaintained `action-rs/*` actions to [dtolnay/rust-toolchain](https://github.com/dtolnay/rust-toolchain), using [Swatinem/rust-cache](https://github.com/Swatinem/rust-cache/) as a cache layer.
* adds a cache layer for LLVM build
* adds a weekly cron schedule for all workflows
* fixes an issue in the docblocks
* add `before` flag to `#[php_startup]`
this calls the user-provided startup function _before_ the classes and
constants registered by the macro system are registered with PHP. by
default the behaviour is to run this function after, which means you
cannot define an interface and use it on a struct.
* cargo fmt
* Add some standard zend interfaces
The zend API also has some standard interfaces it exposes:
c8c09b4aae/Zend/zend_interfaces.h (L27-L33)
```
extern ZEND_API zend_class_entry *zend_ce_traversable;
extern ZEND_API zend_class_entry *zend_ce_aggregate;
extern ZEND_API zend_class_entry *zend_ce_iterator;
extern ZEND_API zend_class_entry *zend_ce_arrayaccess;
extern ZEND_API zend_class_entry *zend_ce_serializable;
extern ZEND_API zend_class_entry *zend_ce_countable;
extern ZEND_API zend_class_entry *zend_ce_stringable;
```
This surfaced in #163 and should make it possible to implement these interfaces.
* Add some links to the php documentation
* update docs.rs bindings
Co-authored-by: David Cole <david.cole1340@gmail.com>
* fix building docs on docs.rs
accidentally removed the docs.rs stub bindings feature in
664981f4fb. docs.rs only has php 7.4 and
therefore cannot build ext-php-rs, so stub bindings are generated prior.
* update docs.rs stub bindings
* Allow passing `--yes` parameter to bypass prompts
Makes this tool usable in automated builds such as Docker containers.
Addresses https://github.com/davidcole1340/ext-php-rs/issues/133
* Update readme and guides
* rustfmt
Co-authored-by: David Cole <david.cole1340@gmail.com>
* Support marking classes as interfaces
This allows passing flags as part of `#[php_class(flags=Interface]` etc, which allows one to mark a class as being an interface.
When a class is an interface, it also shouldn't get a constructor created for it.
* rustfmt
* Specify classes as fully-qualified names in stubs
When stubs are generated, the type annotations don't use a loading `\`, which means they are interpreted as relative to the current namespace. That's wrong, as all types are relative to the root namespace.
* rustfmt
This should fix the errors from the build at
<https://github.com/davidcole1340/ext-php-rs/actions/runs/3145521955/jobs/5112909446>:
Compiling clap v4.0.0
error: Unknown `#[clap(long)]` attribute (`#[arg(long)] exists)
--> crates/cli/src/lib.rs:92:12
|
92 | #[clap(long)]
| ^^^^
error: Unknown `#[clap(long)]` attribute (`#[arg(long)] exists)
--> crates/cli/src/lib.rs:115:12
|
115 | #[clap(long)]
| ^^^^
error: Unknown `#[clap(short)]` attribute (`#[arg(short)] exists)
--> crates/cli/src/lib.rs:134:12
|
134 | #[clap(short, long)]
| ^^^^^
error: could not compile `cargo-php` due to 3 previous errors
warning: build failed, waiting for other jobs to finish...
Error: Process completed with exit code 101.
These errors were probably caused by the release of `clap` 4.0.0
a few hours ago.
