nillable

[Caplan, Michael]

Forgive my ignorance, but why does the WSDL generator define all types as nillable?  Should that not be defined depending  on the prototype  of the method it is bound to?

 

Thanks,

 

Mike

 

E-mail messages may contain viruses, worms, or other malicious code. By reading the message and opening any attachments, the recipient accepts full responsibility for taking protective action against such code. Henry Schein is not liable for any loss or damage arising from this message.

The information in this email is confidential and may be legally privileged. It is intended solely for the addressee(s). Access to this e-mail by anyone else is unauthorized.

[simon...@googlemail.com]

Mike

I don't know either. I took a look at the code and you are right that
it seems to always apply nillable to the types that it finds. Maybe
it's trying to capture some optionality of PHP parameters but I'm not
sure. We need to get Matthew's view on it.

Simon

[Caroline Maynard]

Caplan, Michael wrote:
> Forgive my ignorance, but why does the WSDL generator define all types
> as nillable? Should that not be defined depending on the prototype of
> the method it is bound to?

You're right, there's a lot of information available from the
ReflectionParameter methods (allowsNull(), isOptional(),
isDefaultValueAvailable(), ...) which isn't being exploited at the
moment, but could potentially be used to improve the fidelity of the
generated WSDL. It's likely that Matthew already thought about this when
he developed that code and will know what the issues are. I'd say these
enhancements sound like wish-list items for someone ...

[Caplan, Michael]

Thanks for the feedback! I've opened a request ticket (#10989) relate
to the nillable issue.

Best,

Mike

[Michael Caplan]

I've been looking into this issue further. The condition(s) to
determine if a callable method parameter is nillable more tricky than
I initially thought. I was hoping that a simple
ReflectionParameter::allowsNull() call would be all that is
necessary. However, and this makes perfect sense, all calls to
allowsNull() will return true, with exception to parameters that use
type hinting. Since type hinting does not cover primitives, this does
not cut it.

I'm thinking that this boils down primarily to a PHPdoc issue. With
the @param tag in PEAR's PHPDocumentor, you can split types with a
pipe to indicate multiple acceptable types. So a "@param string|null
$var" could be used to determine if the parameter is nillable or not.
ReflectionParameter::allowsNull() could also be called to validate
claims of something being nillable, should it be not using type hints.

This would require a change to how SCA parses doc blocks to support
piped types. However, probably there should be only one case where
multiple types can be defined (this case), as it doesn't make sense in
other SCA circumstances.

Setting everything to nillable (as it currently does) does not make
sense as I see it. If a system does not get put into place that
allows for users to control how nillable is used in the generated
WSDL, as a minimum, I think it should be suppressed. I think it makes
more sense to assume all parameters as not accepting null values, then
the reverse.

Thoughts?

Mike

[Graham Charters]

Hi Mike,

One of the goals of the SCA annotations has been to try to preserve
phpDocumentor generation, so I like your suggestion a lot. I took a
look at the phpDocumentor documentation and could only see mention of
the pipe for multiple function returns, but not for parameters. I
gave it a whirl for both and phpDocumentor 1.3.0 doesn't appear to do
anything special with the pipe and doesn't care if it's included in an
@param.

If we include the modification suggested in another thread where we
would change the way complex types are specified to use the #
character (will improve the quality of the phpDocumentor generation),
then an example SCA component might look like this:

/**
* Service for managing email contacts
*
* @service
* @binding.soap
* @types http://example.org/contacts contacts.xsd
*
*/
class ContactService {

/**
* Retrieve contact details
*
* @param string|null $shortname The short name of the contact
* @return http://example.org/contacts#contact|null The full
contact details
*/
public function retrieve($shortname) {
}

}

Let me know if I've misunderstood your proposal.

The only reason I can think for the generation of nillable all the
time would be to support as many calling options with as little
configuration as possible. I can understand why the other way round
might be preferable and adding control through the annotations gets my
+1.

Graham

On 11 May, 18:40, Michael Caplan <michael.cap...@henryschein.com>
wrote:

[Caplan, Michael]

Hi Graham,

Thanks for the feedback. Last I checked against phpDocumentor output (and maybe I should validated this again), phpDocumentor will handle pipes for @param. If I remember correctly, the @return parser uses the same parsing logic as the @param parser. I too didn't see any mention of this in the phpDocumentor manual, but perhaps this is an omission. Perhaps we could clarify this with the package developers.

Otherwise, I do like # notation in the referenced schema.

Best,

Mike

Hi Mike,

}

Graham

E-mail messages may contain viruses, worms, or other malicious code. By reading the message and opening any attachments, the recipient accepts full responsibility for taking protective action against such code. Henry Schein is not liable for any loss or damage arising from this message.

[Caplan, Michael]

Hi Graham,

FYI, I just got word back from a PHPDocumentor developer re: @param
support for multiple types:

Hello Mike,

That functionality is both in there and supported, though it looks like
we could improve on how we demonstrate it in our manual. I've opened
PEAR bug #11032
(http://pear.php.net/bugs/bug.php?id=11032) to get the manual updated
with better examples showing that "param type1|type2" usage, and will
also add more detail to the return tag's doc.

Thanks for the posting...
Chuck

Now that we know that this is supported behavior, any thoughts on the
two outlined methods for supporting nillable parameters?

Best,

Mike

> -----Original Message-----
> From: php...@googlegroups.com [mailto:php...@googlegroups.com] On

> Behalf Of Graham Charters
> Sent: May 12, 2007 6:16 PM
> To: phpsoa
> Subject: [phpsoa] Re: nillable
>
>

[Matthew Peters]

(Joining this thread a week late :-))

Mike, you have done a fantastic job of researching the options. I'm
puzzled why you say _two_ options: isn't there just one surviving
idea, which is what you and Graham have converged upon, the use of the
pipe symbol for both @param and @return, as in:

* @return http://example.org/contacts#contact|null The full
contact details

I agree that this is a fine idea. Would you like me to go ahead and
implement it? The parsing of the annotations is a bit of a rough area
of the code so it does not seem fair that you should have to implement
it as well, especially as you have made several other contributions in
quick succession recently. But you would however be very welcome to do
so if you wanted :-)

Matthew

On May 14, 2:37 pm, "Caplan, Michael" <Michael.Cap...@henryschein.com>
wrote:

> > * @returnhttp://example.org/contacts#contact|null The full

[Caplan, Michael]

Hi Matthew,

I guess I am a little confused about the # notation that Graham outlined
(and wondered if that was just a slightly different way to handle the
problem). Am I correct that Graham is getting at a new notation for
specifying elements from a schema?

IE:

@return element http://Schema_NameSpace Description

Becomes:

@return http://Schema_NameSpace#element Description

As for implementing pipe support in types, I spent some time in the code
thinking through what this could programmatically look like. But, I'm
not so sure about the structural changes I came up with and possible
side effects. Also, I wouldn't want to interfere with an architecture
choices that may be tied to future initiatives. This said, I could
submit a patch if it would be of assistance, but I wouldn't be able to
get to it for at least a week. The sort of it, yes please implement it.
Let me know if I can help in any way.

[Graham Charters]

Hi Mike,

Thanks for clarifying the use of pipe with the phpDocumentor
developer.

Yes, the # notation was simply an alternative way to identify a
complex type in a schema. It's largely orthogonal to nillable but I
mentioned it for a few reasons:

1. To raise the idea of us making both changes together since they
will be in the same area of code.
2. As an example where we could improve preserving the phpDocumentor
generation (at the moment the namespace gets generated into the
description :-( ).
3. To solicit more feedback.

My apologies if I caused some confusion. I hope this helps clarify my
intentions.

Graham.

On 15 May, 18:14, "Caplan, Michael" <Michael.Cap...@henryschein.com>
wrote:

[Matthew Peters]

Good, it gets clearer all the time.

I am going to block out tomorrow to work on this. I will probably aim
to implement the pipe, and do it in a way to make it easier to
implement the #. The code in there at the moment is all rather quick
and dirty string handling that ends up populating an associative
array. I think I will try to turn this into building an object: a
methodSignature object, perhaps, that contains an argumentList object,
which in turn contains argument objects, which have a list of
allowable types etc etc etc.

Also tomorrow, I want to get round to incorporating the other fixes
you, Mike, have sent us in a couple of the pecl defects. You are
leading the way in the code contribution stakes.

It's good working with you all.

Matthew

[Caplan, Michael]

Hi Graham,

Yes, I think I am on the same page now :)

5++ on making SCA supported docblock notation consistent with
phpDocumentor.

[Matthew Peters]

I just had a go at this and checked the changes in to the DUNLIN
branch. It's now the case that you only get nillable="true" in the
wsdl if you have a type that specifies a choice with null e.g.
@param string|null $a
or
@return boolean|null

I realised as I started that we had not talked about what to do with
e.g. float|string etc. which could in principle be implemented with a
choice of some sort in the wsdl. I chickened out and only allowed |
null.

The other thing I chickened out of was restructuring the way the
parameter and return information is held and passed around. I left it
as an associative array but now with a 'nillable' => true/false
element as well. I don't like it all that much but it was quick and
easy. (The path of least resistance often is quick and easy ... to
start with ... :-) )

Matthew

On May 16, 12:50 pm, "Caplan, Michael"