Create an issue for @struct (?)

[mindplay-dk]

@mvriel there's a TODO in the doc mentioning @struct, but it doesn't say what it is.

For this, and any other known "holes" in the spec, can you open issues in the bug tracker please, so we can pick them up and work on them?

As you can see, I'm putting in a lot of time on this project this week - I plan on spending more time in the coming weeks making a push to get this moving forward again. Please open issues for whatever you know is incomplete or missing, to point me wherever I can help, and create context for debate.

Thanks! :-)

[GrzegorzDrozd]

@ struct tag is probably related to this: https://gist.github.com/mvriel/3822861 Short: create virtual structure that can be used for example to document hashmap "fields" for $params|$options for methods and functions. I am a big fan of including that!

[mindplay-dk]

@GrzegorzDrozd off-topic, but that's not what arrays are for - this feature only serves an outdated legacy anti-pattern. Real objects perform better, and it's what the language provides for exactly this case.

I am a big fan of focusing on current/modern php patterns - if this one isn't dead, it sure should be.

[Fleshgrinder]

@mindplay-dk :+1:

[jacobsantos]

@mindplay-dk Hating on WordPress. Shame man. Shame. WordPress didn't get where it was by utilizing the best patterns and best practices. It got where it is by GSD (Get Shit Done) and being a maverick with programming techniques. When better programmers say, "It is best to not do that," WordPress devs totally ignore that and do it anyway.

[Fleshgrinder]

The WordPress people are doing what they do because of the lack of alternatives when they started and now they are stuck with interfaces that have to honor backward compatibility. Even if they wanted to change that, they would need serious man power to do so because that stuff is spread all over their code base. A standard or recommendation should encourage people to get shit done according to best current practice. Of course those practices will change in the future, as they did in the past; that is by the way the reason why I do not like the PSR system that much.

Of course opinions will vary highly, especially because PHP is a multi-paradigm language. However, I think we all agree that object oriented programming is what we want, hence, associative arrays as work horses are obsolete.

[mindplay-dk]

@jacobsantos I can't tell if you're being facetious? Not enough smiley faces ;-) ;-) ;-)

I never said WordPress. Or Drupal. I was obviously thinking it, but you said it, not me ;-)

@Fleshgrinder

The WordPress people are doing what they do because of the lack of alternatives when they started and now they are stuck with interfaces that have to honor backward compatibility

Tru dat.

[jacobsantos]

@mindplay-dk They need to call me Poe's Law, because I live it every day. I am told I should use smilies more, but I'm not sure it works in every instance.

I will say that if that was the intent and I do think that it is useful to allow for this feature to document arrays, which is notoriously difficult.

That said, I'm not sure if it might be better to use @struct in order to document Anemic Objects. To say, "this data object is for storing fields and is complete." I guess technically, anemic objects aren't best practice either, but they are useful. Should you always have accessors and mutators? In Java? Yes. In PHP? It depends.

[mindplay-dk]

I'm all for anemic models, I don't think that has anything to do with abuse of arrays? Even anemic models need things like validation for consistency etc.

Either way, I'm against anything that propagates outdated practice. I don't care how popular X may be - if they refuse to break BC to keep up with time, that's not a problem to be addressed by modern standards. Sorry. On Oct 20, 2015 12:31 AM, "Jacob Santos" notifications@github.com wrote:

@mindplay-dk https://github.com/mindplay-dk They need to call me Poe's Law, because I live it every day. I am told I should use smilies more, but I'm not sure it works in every instance.

I will say that if that was the intent and I do think that it is useful to allow for this feature to document arrays, which is notoriously difficult.

That said, I'm not sure if it might be better to use @struct in order to document Anemic Objects. To say, "this data object is for storing fields and is complete." I guess technically, anemic objects aren't best practice either, but they are useful. Should you always have accessors and mutators? In Java? Yes. In PHP? It depends.

— Reply to this email directly or view it on GitHub https://github.com/phpDocumentor/fig-standards/issues/92#issuecomment-149366064 .

[Fleshgrinder]

Anemic !== DTO, a distinction that is important. Anemic models are an anti-pattern and should not be encouraged.

[mindplay-dk]

@Fleshgrinder this is totally off-topic, but just to clarify, I'm of course not for strictly anemic models - I of course put things like validations and calculations in the classes where they belong. What I advocate is thin models and a service-oriented approach for (basically) anything involving more than one type of entity. Just to be clear :-)

[jacobsantos]

@Fleshgrinder Perhaps. I will say that anemic objects are sometimes used as a poor man's DTO in PHP. Not as popular as using arrays to pass data. PHP doesn't tend to follow OOP best practices and while I don't often create anemic objects, because it seems wrong, I do see why they could be used.

That said, I have no idea what @struct means or what context it was meant to be used. My suggestion that it could be used for anemic objects to let programmers know that the class is complete, even without additional methods, accessors or mutators. "A structure is simply an object with attributes". I guess technically, this suggestion is not necessary, since you could just define the class as @api and define attributes as public and with @api as well. Although, I'm not sure if you could use @api with class fields. It would then tell the programmer that the field must not be changed or if it is to be changed, to ensure that the change is backwards compatible.

[mindplay-dk]

I just learned about @api - so it is basically the opposite of the internal attribute in C# ... That's nuts - I'm going to open a separate issue to address that. On Oct 21, 2015 12:52 AM, "Jacob Santos" notifications@github.com wrote:

@Fleshgrinder https://github.com/Fleshgrinder Perhaps. I will say that anemic objects are sometimes used as a poor man's DTO in PHP. Not as popular as using arrays to pass data. PHP doesn't tend to follow OOP best practices and while I don't often create anemic objects, because it seems wrong, I do see why they could be used.

That said, I have no idea what @struct means or what context it was meant to be used. My suggestion that it could be used for anemic objects to let programmers know that the class is complete, even without additional methods, accessors or mutators. "A structure is simply an object with attributes". I guess technically, this suggestion is not necessary, since you could just define the class as @api and define attributes as public and with @api as well. Although, I'm not sure if you could use @api with class fields. It would then tell the programmer that the field must not be changed or if it is to be changed, to ensure that the change is backwards compatible.

— Reply to this email directly or view it on GitHub https://github.com/phpDocumentor/fig-standards/issues/92#issuecomment-149725061 .

[Fleshgrinder]

I will have to revisit the @struct tag at some point because I also don't know what it is meant for exactly. However, it is hard to judge anything, because the main document is way too far behind all issues and merge requests. :disappointed:

[mindplay-dk]

the main document is way too far behind all issues and merge requests

I wish there was an actual platform or system for editing, discussing and collaborating on PSRs - I have been thinking that for a while... all I know of is beegit and it's not free...

[GrzegorzDrozd]

Hi. @mindplay-dk

off-topic, but that's not what arrays are for - this feature only serves an outdated legacy anti-pattern.

I know. This was just an example. I think @ struct can be usefull not only to describe antipatern of using object fields for config. It can be used also to describe an array (of rows) that you return from a method. @ return fooStruct[] @ struct fooStruct { @ type int id @ type string label .... } So the question is: do we want generic way of describing structured data? ps: if we don't put using struct as a way of describing options for an object in the example section of struct description then maybe people will not use it for that ;) :D

[mindplay-dk]

If an array has a known, fixed set of keys, it's effectively an object, and should be declared as an object. I can't think of a use-case. Even if you wanted, for example, PDO to records with a known structure, you can ask it to map them to objects, which is more efficient both in terms of CPU usage and memory consumption - why invent means of avoiding the language?

The only real use-case is legacy code and anti-patterns like $options, but honestly, whatever - if you guys need it, go ahead, it's not going to do any harm for those of using real objects.

[Fleshgrinder]

It is not only good for legacy code, one can use it for real DTOs (e.g. arrays and objects [\stdClass] returned from database results).

[mindplay-dk]

It is not only good for legacy code, one can use it for real DTOs (e.g. arrays and objects [\stdClass] returned from database results).

If you're going to declare the "properties" as array keys anyway, you might as well declare a real class - it's precisely the same work load, with better memory characteristics, less CPU overhead, and actual type-checks if you pass the DTOs to methods.

PDOStatement::fetchObject accepts a class-name - you can use this today, without waiting first for this RFC to define it, then waiting for tools to actually support it.

I'm sorry, but it really is good only for legacy code and bad code. (sorry, WordPress.)

[Fleshgrinder]

Yes, I know (same is true for mysqli stuff) it might have been a bad example. Let's say json_decode then. :wink:

Anyways, I just want to collect arguments. Personally I think that real DTOs should be converted to real objects at the moment they enter the software.

[mindplay-dk]

Arguably, you could annotate raw input from a JSON/REST API, sure - personally I would map those to objects in my client implementation either way, now if you're going to do both (pointless) all you've managed to do is double the burden.

Personally I think that real DTOs should be converted to real objects at the moment they enter the software.

Man, why are we debating this? Okay, I'm done ;-)

[Fleshgrinder]

Yeah, i think we are on the same page here for once. :relaxed:

[mvriel]

FYI: I have removed all references to array interpretation and @struct. Because this is a contentious item that is desired but no syntax could be defined that would be definitive I have decided to leave it out of PSR-5 and allow for it to be added in a future PSR.

I one of the participants feels differently or would discuss this item I suggest doing that on the mailing list since there will hopefully be more opinions that can assist