Skip to content

Please fix api.php #33

Open
giac opened this Issue Aug 3, 2011 · 20 comments

6 participants

@giac
giac commented Aug 3, 2011

Hi there,

In api.php all the constants are defined in the ZMQSocket class, but they are actually in the ZMQ class.
If I try to use for example ZMQSocket::SOCKET_PUB I get a fatal error.
Also please add ZMQ::SOCKET_PULL there.

Unless this is needed for future changes this is broken since commit d44061f

Thanks for your work!

@mkoppanen
Owner

Hi,

i think better idea might be creating a script that creates api.php automatically. This file is really needed only for eclipse and the like code completion.

@aik099
aik099 commented Mar 2, 2012

I also got the same problem. I imported it into PHPStorm IDE and get fatal errors about missing constants.

Will be this api.php file fixed soon?

@aik099
aik099 commented Mar 2, 2012

It appears that most accurate version is here http://php.zero.mq/, but you can't really download all class declarations from there.

@mkoppanen
Owner

Hi,

this should be fairly easy task with reflection. I'll try to update it today

@aik099
aik099 commented Mar 11, 2012

Any progress on this one?

I can use Reflection API to get names of constants and method, but how do I get these nice PHPDoc documentation for each of them?

@SegFaulty

had the same problem (for other extensions too)
so i created DocThor

ZMQ-API v1.0.3 is the example

but you can build your own with it

@mkoppanen
Owner

This is excellent. I am very short on time at the moment but I'll use DocThor to generate new api.php

@aik099
aik099 commented Mar 31, 2012

Are you sure that https://github.com/SegFaulty/DocThor/wiki/zmq is generated according to latest version of php extension?

ZMQDevice constructor should have 3 arguments:
$device_type
$frontend
$backend

according to their C api http://api.zeromq.org/2-1:zmq-device and PHP samples http://zguide.zeromq.org/php:msgqueue.

I'm actually trying to create new version of api.php file with all comments are references to API website to create more useful hints in auto-complete.

Maybe there is an error in PHP bindings.

@SegFaulty

first: https://github.com/SegFaulty/DocThor/wiki/zmq is updated , now with some more information from the source (new DocThor Feature --sourceDir)

ZMQDevice ..
don't know, you are right the examples refer 3 arguments but I get:
$device = new ZMQDevice(ZMQ::DEVICE_QUEUE, $frontend, $backend);
Warning: ZMQDevice::__construct() expects exactly 2 parameters, 3 given in ,,
AND i have to use ZMQDevice::run()

a look at the extension sources here https://github.com/mkoppanen/php-zmq/blob/master/zmq.c#L1138 shows 2 args

@mkoppanen
Owner

I removed the first arg as it had no effect.

@SegFaulty

well, that explains it...

btw. with the newest DocThor feature, i found:

8 inconsistencies
inconsistent parameter name: ZMQContext::__construct reflection:persistent sourceCode:is_persistent
inconsistent parameter name: ZMQSocket::__construct reflection:ZMQContext sourceCode:context
inconsistent parameter name: ZMQSocket::send reflection:mode sourceCode:flags
inconsistent parameter name: ZMQSocket::sendmulti reflection:message sourceCode:messages
inconsistent parameter name: ZMQSocket::sendmulti reflection:mode sourceCode:flags
inconsistent parameter name: ZMQPoll::add reflection:entry sourceCode:object
inconsistent parameter name: ZMQPoll::add reflection:type sourceCode:events
inconsistent parameter name: ZMQPoll::remove reflection:remove sourceCode:item

minor .. but maybe related to this issue :-)

@aik099
aik099 commented Apr 1, 2012

Since current PHP bindings were out there for quite a long time, then maybe in PHP there is another way to specify device type, but I really don't know how.

@mkoppanen
Owner

The device type has never made any difference. If you look at ZeroMQ source the device type parameter is ignored.

@aik099
aik099 commented Apr 1, 2012

I've just noticed that this page http://api.zeromq.org/2-0-11:_start is API documentation for ZeroMQ 2.0.11, where zmq_device function exists and it has 3 parameters.

But I'm using 2.1.11 (http://api.zeromq.org/2-1-1:_start) version of ZeroMQ library where there is no zmq_device function and instead a separate functions are created:

  • zmq_streamer
  • zmq_poll
  • zmq_queue

This makes me think, that they should be represented as a separate ZMQDevice class descendants in PHP bindings.

@aik099
aik099 commented Apr 1, 2012

From documentation:
If you're like most ØMQ users, at this stage your mind is starting to think, "what kind of evil stuff can I do if I plug random socket types into devices?" The short answer is: don't do it. You can mix socket types but the results are going to be weird. So stick to using ROUTER/DEALER for queue devices, SUB/PUB for forwarders and PULL/PUSH for streamers.

Maybe in PHP bindings it's automatic - device type is matched to socket type you pass, while creating a device?

@mkoppanen
Owner

If you look a the actual ZeroMQ 2.1.x source code here:

https://github.com/zeromq/zeromq2-1/blob/master/src/zmq.cpp#L764

The 'int device' parameter is passed (which is the device type) but when the actual device code is called it's not being passed on. The device type parameter exists there only for backwards compatibility i think.

@mkoppanen
Owner

I would appreciate if someone would provide step by step docthor instructions which i can link to.

@phuedx
phuedx commented Feb 4, 2015

I've just run DocThor against master and this is the result: https://gist.github.com/phuedx/5f727191b30fd8969825

@Orvid
Orvid commented Sep 10, 2015

Alright, so, as HHVM does require native functions to be properly declared, I have a version of the API that should be almost identical to the actual one, although documentation is needed for anything that wasn't in the original api.php, which I've marked with @EXTRA. Here is the main file. That file includes the documentation that was already there, but doesn't include any of the constants that are defined. Changes will have to be made to that as it's marked up for direct use in HHVM, so pretty much everything is strongly typed in the API. For a complete list of constants, you'd see here, which is the Hack API file for it. All documentation was stripped from the second file. Note that the constant list is based on a build against ZMQ v4.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.