# When will the extension and embedding APIs ever be cleaned or documented?

- Thread: https://externals.io/message/72562
- Original archive: https://news-web.php.net/php.internals/72562
- Started by Kevin Ingwersen on 2014-02-13T20:22:05+00:00
- Messages: 8
- Reply by email to internals@lists.php.net
- More for agents: search with https://externals.io/search.md?q={query} · RFCs at https://externals.io/rfc.md · JSON API at https://externals.io/api · documentation at https://externals.io/llms.txt

---

## #72562 — Kevin Ingwersen — 2014-02-13T20:22:05+00:00

URL: https://externals.io/message/72562#72562

Hey.

Just a while ago, i started writing a C++ library, that I would like to utilize in PHP. Since the original aproach was made in C++, I would like to keep the OOP syntax in PHP.

Already, months ago, I had tried to find ways to write useful PHP modules. But the major problem was always: How. I easily found documentation about adding functions…and how to expose a void pointer in the form of a „Resource“. But that was all that was ever properly documented. The OO module api was never really documented, and yet, is still hard to figure out. I was sent a slideshow of the api…but is a set of slides a really well made documentation? I think not.

Many of you internals probably know the APIs needed to do these things:

	- Create a class with public/private/protected methods - thus making a class final.
	- Being able to store a pointer to forgein objects into the class, to re-use it.

I have been learning to use the v8 API a lot and it has a very clean syntax. A third-party scripting language brought it even so far, that it could almost map native types to script types - but that was pure C++ - both of them.

My simple question is hereby:

	- When will the module API ever be properly documented?


Now, at some point, I want to embed PHP into my project. Like, I have the idea for a project, but I want to utilize a scripting language for it. None of the languages supports the syntax that I am used from PHP. And furthermore, neither v8 or PHP have an easy embedding way. V8 needs to utilize GYP, and PHP autotools. Both not very optimal, but eh.
I simply want to know how I can take advantage of the embed-SAPI for my application - and how I can possibly integrate my project into PHP’s build process. Must I maintain configure.ac+makefile.am? Or is there anothe way to directly implement my code into the PHP build process?

And my question hereby is:

	- When will the embed-SAPI be documented in a way, that it can be used? I havent found any useful docs for embedding PHP…

Hope you understand what I am trying to ask ^^;


Kind regards, Ingwie.

---

## #72563 — Nikita Popov — 2014-02-13T20:45:33+00:00

URL: https://externals.io/message/72562#72563 · In reply to: #72562

On Thu, Feb 13, 2014 at 9:22 PM, Kevin Ingwersen
<ingwie2000@googlemail.com>wrote:

> Hey.
>
> Just a while ago, i started writing a C++ library, that I would like to
> utilize in PHP. Since the original aproach was made in C++, I would like to
> keep the OOP syntax in PHP.
>
> Already, months ago, I had tried to find ways to write useful PHP modules.
> But the major problem was always: How. I easily found documentation about
> adding functions...and how to expose a void pointer in the form of a
> "Resource". But that was all that was ever properly documented. The OO
> module api was never really documented, and yet, is still hard to figure
> out. I was sent a slideshow of the api...but is a set of slides a really well
> made documentation? I think not.
>
> Many of you internals probably know the APIs needed to do these things:
>
>         - Create a class with public/private/protected methods - thus
> making a class final.
>         - Being able to store a pointer to forgein objects into the class,
> to re-use it.
>

I think we have a pretty good coverage of object and class APIs here:
http://www.phpinternalsbook.com :)


> I have been learning to use the v8 API a lot and it has a very clean
> syntax. A third-party scripting language brought it even so far, that it
> could almost map native types to script types - but that was pure C++ -
> both of them.
>

V8 has the benefit of being written in C++ and being a lot newer. HHVM has
really nice extension APIs, all courtesy to C++. But a number of core devs
are rather opposed to using a more powerful language as the basis for PHP
;) *Glares at Pierre*

Nikita

---

## #72569 — johannes@schlueters.de — 2014-02-13T23:04:01+00:00

URL: https://externals.io/message/72562#72569 · In reply to: #72563

> 
> I think we have a pretty good coverage of object and class APIs here:
> http://www.phpinternalsbook.com :)
> 
Why is that an eternal project not part of the documentation?
Contributors seem to be php.net contributors ... sad :(
> 
> > […]
> that it
> > […]
> ++ -
> > […]
> 
> V8 has the benefit of being written in C++ and being a lot newer. HHVM
> has really nice extension APIs, all courtesy to C++. But a number of
> core devs are rather opposed to using a more powerful language as the
> basis for PHP
> ;) *Glares at Pierre*
> 
Well, C++ has tools which would help to provide way cleaner APIs in
efficient manner. PHP's API has a >15 years history though with tons of
modules depending on it. Any major break is bad. 

Mind: "Compatibility is a feature." (Bjarne Stroustrup) The fact that 10
years old extensions can be used with php git master with quite little
work is not only a help for old users but also promise to new users that
their investment won't be lost easily.

johannes

---

## #72572 — Kevin Ingwersen — 2014-02-14T00:17:44+00:00

URL: https://externals.io/message/72562#72572 · In reply to: #72569

Am Fr. Feb. 14 2014 00:04:01 schrieb Johannes Schlüter:
> Mind: "Compatibility is a feature." (Bjarne Stroustrup) The fact that 10
> years old extensions can be used with php git master with quite little
> work is not only a help for old users but also promise to new users that
> their investment won't be lost easily.

But what if there was something like a wrapper above the old api, to give it a cleaner appearance, so people could choose to work with the newer, or older, API?

BTW, in the API „book“, I dont find what I am looking for; storing a forgein thing into the object. Like if I was to write a PHP module that exports a PHP class, I would like to create a class instance to a C++ class, and store that instance within the php object (struct?). Like:

	zval* this = getThis();
	MyClass* mc = (MyClass*)get_pointer_from_zvalthis);

And, well, vice-versa.

Otherwise, that phpinternalsbook is very detailed, and I like how its written :)

Although its no real PHP project - why not just link it in the php.net docs? o.o

---

## #72573 — Chris Wright — 2014-02-14T00:54:16+00:00

URL: https://externals.io/message/72562#72573

Apologies for the double post Kevin, I forgot to copy the list in to the
first


> BTW, in the API "book", I dont find what I am looking for; storing
> a forgein thing into the object.

Take a look at:

http://www.kchodorow.com/blog/2011/08/11/php-extensions-made-eldrich-classes/

...under the heading "attaching structs" for a basic run down of what (I
think) you are trying to do. I can't claim to be an expert so I can't vouch
for how current or generally correct this information is, though.

---

## #72577 — johannes@schlueters.de — 2014-02-14T01:02:37+00:00

URL: https://externals.io/message/72562#72577 · In reply to: #72572

> Am Fr. Feb. 14 2014 00:04:01 schrieb Johannes Schlüter:
> > […]
> 
> But what if there was something like a wrapper above the old api, to
> give it a cleaner appearance, so people could choose to work with the
> newer, or older, API?

Well, there wasn't a satisfiable API proposed, yet. The current "API" is
quite wide making it hard to wrap without requiring too much "escape
points". There are projects like https://github.com/moriyoshi/boost.php
though. (Last change 4 years ago ...)

In the end: Once people are used to it it isnot toooo much of a urden to
use the existing interface in most cases.

> BTW, in the API „book“, I dont find what I am looking for; storing a
> forgein thing into the object. Like if I was to write a PHP module
> that exports a PHP class, I would like to create a class instance to a
> C++ class, and store that instance within the php object (struct?).
> Like:
> 
> 	zval* this = getThis();
> 	MyClass* mc = (MyClass*)get_pointer_from_zvalthis);
> 
> And, well, vice-versa.

Maybe this helps:
http://talks.somabo.de/200903_montreal_php_extension_writing.pdf
starting ca. slide 89. 
Mind that this might be a bit outdated, property handling changed a tiny
bit, the UPRADING.INTERNALS file in a recent PHP distribution should
have details if you run into issues ... ignore the comment on the
UPGRADING file ... I can't seem to find the relevant reference ..
damn ... notably direct manipulation of properties via zend_hash_copy as
on slide 90 is to be replaced with object_properties_init(), if you hit
issues there please ask again and I (or maybe/hopefully somebody else)
can dig deeper and help more.

> Otherwise, that phpinternalsbook is very detailed, and I like how its
> written :)
> 
> Although its no real PHP project - why not just link it in the php.net
> docs? o.o

That probably might be done, I'd prefer integration so more people can
update it ... I myself wasn't aware of the existence before.

johannes

---

## #72579 — Christopher Jones — 2014-02-14T02:03:25+00:00

URL: https://externals.io/message/72562#72579 · In reply to: #72572

> Otherwise, that phpinternalsbook is very detailed, and I like how its written :)
>
> Although its no real PHP project - why not just link it in the php.net docs? o.o
>

You might be interested in looking at https://wiki.php.net/internals/references

Chris

-- 
christopher.jones@oracle.com  http://twitter.com/ghrd
Free PHP & Oracle book:
http://www.oracle.com/technetwork/topics/php/underground-php-oracle-manual-098250.html

---

## #72586 — Nikita Popov — 2014-02-14T09:54:00+00:00

URL: https://externals.io/message/72562#72586 · In reply to: #72572

On Fri, Feb 14, 2014 at 1:17 AM, Kevin Ingwersen
<ingwie2000@googlemail.com>wrote:

> Am Fr. Feb. 14 2014 00:04:01 schrieb Johannes Schlüter:
> > […]
>
> But what if there was something like a wrapper above the old api, to give
> it a cleaner appearance, so people could choose to work with the newer, or
> older, API?
>
> BTW, in the API "book", I dont find what I am looking for; storing a
> forgein thing into the object. Like if I was to write a PHP module that
> exports a PHP class, I would like to create a class instance to a C++
> class, and store that instance within the php object (struct?). Like:
>
>         zval* this = getThis();
>         MyClass* mc = (MyClass*)get_pointer_from_zvalthis);
>
> And, well, vice-versa.
>

This is covered in
http://www.phpinternalsbook.com/classes_objects/custom_object_storage.htmland
http://www.phpinternalsbook.com/classes_objects/custom_object_storage.html#overriding-create-objectin
particular :) In the code sample there you'd replace "long
additional_property" with "MyClass *my_class" (and add a delete call in the
free_storage handler and a new call in create_object).

Nikita