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>
* 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
Clippy linting had some errors:
error: boolean to int conversion using if
Error: --> src/builders/module.rs:59:29
|
59 | zend_debug: if PHP_DEBUG { 1 } else { 0 },
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: replace with from: `u8::from(PHP_DEBUG)`
|
= note: `-D clippy::bool-to-int-with-if` implied by `-D warnings`
= note: `PHP_DEBUG as u8` or `PHP_DEBUG.into()` can also be valid options
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#bool_to_int_with_if
error: boolean to int conversion using if
Error: --> src/builders/module.rs:60:22
|
60 | zts: if PHP_ZTS { 1 } else { 0 },
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: replace with from: `u8::from(PHP_ZTS)`
|
= note: `PHP_ZTS as u8` or `PHP_ZTS.into()` can also be valid options
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#bool_to_int_with_if
error: could not compile `ext-php-rs` due to 2 previous errors
This commit tries to fix those.
* Preliminary Windows support
* Start work on cross-platform build script
* Fix compilation on macOS
* Updated README, tidied up build script
* Check linker version before starting compilation
It doesn't seem like it's possible to change the linker from within the
build script, however, we can retrieve the linker in use and give the
user a suggestion if the linker will not work.
* Switch to using Github repository for bindgen
* Split Windows and Unix implementations into two files
* Fix building on Windows
* Remove `reqwest` and `zip` as dependencies on Unix
* Fix guide tests on Windows
* Started work on Windows CI
* runs -> run
* Use preinstalled LLVM on Windows
* Debugging for Windows CI
* Switch to upstream `rust-bindgen` master branch
* Switch to `rust-lld` for Windows linking
* Don't compile `cargo-php` on Windows
* Switch to using skeptic for tests
* cargo-php: Disable stub generation, fix ext install/remove
The plan is to replace the stub generation by generating them with PHP
code. This is cross-platform and means we don't need to worry about ABI.
We also don't need to embed information into the library.
* cargo-php: Fix on unix OS
* Fix clippy lint
* Updated README
* Re-add CI for Unix + PHP 8.0
* Fix building on thread-safe PHP
* Tidy up build scripts
* Use dynamic lookup on Linux, test with TS Windows
* Define `ZTS` when compiling PHP ZTS
* Combine Windows and Unix CI, fix linking for Win32TS
* Fix exclusions in build CI
* rust-toolchain -> rust
* Set LLVM version
* Only build docs.rs on Ubuntu PHP 8.1
* Fix build on Linux thread-safe
* Update guide example
This wasn't the case because of `PhantomData<T>` inside the metadata.
Replacing this with `PhantomData<AtomicPtr<T>>` ensures that the
metadata will always be `Send + Sync`.
* Bump PHP API version, remove flags removed from PHP API
See following commits:
- 70195c3561
- b5746a4c7f
* Add PHP 8.1 to CI
* Clippy lint
* Fix PHP 8.1 support with new features
* Change describe types to C ABI, check ext-php-rs version
Rust doesn't have a stable ABI so the describe function and types are
now C ABI compatible, however, the internal types `Cow`, `Vec`, `Option`
aren't.
Check `ext-php-rs` versions to check compatibility between the CLI and
the extension.
* CLI requires 0.7.1
* Bump versions
* Replace standard library types with ABI-stable replacements
* Change option type
* started work on stub generator
* Worked on stub CLI tool
* Unused import
* Account for namespaces in function and class names
* Add support for docblocks on structs
* Push Rust comments to stubs
* Add indentation to stub generation
* Add CLI application to install and generate stubs
This time CLI application is defined on user side, called with `cargo
run -- ..args..`
* Export anyhow result
* Add constants to stub file
* Removed stub symbols
No longer required as we are now building while also linking to PHP.
Keeping the stubs causes the stubs to override the real symbols in the
extension.
* Fix stubs for real this time
Removed stub symbols as they were being included in the extension
dylib, fix by loading the PHP executable as a dylib, loading the
required symbols globally.
* Maybe actually fix stubs this time
* Forgot to remove PHP binary loading
* let's give this another go... cargo subcommand
Now called via `cargo php <install,stubs>`.
* Added `remove` command
* Tidied up cargo-php, commented, set up CI
* Fix return types with non-ident types
* define namespace ordering
* Fix tests, replace `Self` when in outer context
* Moved allowed bindings into separate file
* Update guide with CLI instructions
* Disable serialization and unserialization on classes
Classes that have associated Rust types cannot be serialized for
obvious reasons so these need to be disabled. Disabling these actions
changes in PHP 8.1 to use a flag, so that will need to be solved with
PHP 8.1 support. Closes#97
* update docs stubs
* Fixed `ArgParser` lifetimes
Now stores a mutable reference to the underlying zval. Instead of
passing the execution data to the arg parser, a vector of args is now
passed to prevent a shared lifetime issue with the `$this` object.
* Implememt from traits for classes
* Added `ZBox` and `ZBoxable`
* Implement `ZBoxable` for `ZendStr`
Build for all f eatures on CI
* Replace `OwnedZendObject` with `ZBox<ZendObject>`
* Replace `ClassObject` with `ZBox<ZendClassObject>`
Fixed deserialization bug
Panic when uninitialized - better than UB
* Replace `OwnedHashTable` with `ZBox<HashTable>`
* Remove `MaybeUninit` from `ZendClassObject`
