Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PHP documentation #3523

Closed
TheFox opened this Issue Dec 5, 2018 · 3 comments

Comments

Projects
None yet
2 participants
@TheFox
Copy link

TheFox commented Dec 5, 2018

I already talked to @lukeholder about this topic.

It seems there is a big lack of documentation for Craft CMS in reagarding of PHP. I want to have more PHP examples and tutorials how I solve certain problems.

For example, how to I trigger an Event using PHP? How to I store an Element? Why the hack do I first have to go to a Slack channel to get examples for this topics? This should be available in the documentation. When I open any Craft documentation I find nothing helpful. I would expect from such a big framework like Craft and Craft Commerce to provide more PHP examples and tutorials for every major use case.

Symfony has tutorials about almost everything. I'm talking about, for example, like this. You have everything in place. How my Controller should look like. Where to place files. What the template should look like.

Or for Yii, like this.

I already opened #582 at Commerce. Because it's not only the CMS. It's the whole project. It's totally fine when Commerce is not released yet and has no documentation. But Craft 3 is already released and has a big lack of documentation.

Until yesterday, the Orders documentation was only two (!) sentenses long. Two. How can this happen? Let's focus on the Orders. Even yet there is no documentation for PHP on this page. How can I create an Order using PHP? Which Order Class to I have to use to create a new one? Should I use Order Element? Or Order Model? Order Record? Which function do I have to call to actually store my new Order object to the database? Should I rather use ...->update() or \Craft::$app->getElements()->saveElement(...)? How can I trigger an Event for an Order? How can I create an Event hook for an Order? How can I fuck myself? The kind of questions I would expect to be answered in a documentation.

The Orders is just an example. It's the same lack on all other topics as well. Every time I asked in the Slack channel I get forwarded to some random PHP code, no matter if it fits the topic or not. The problem for new people like me, when getting forwarded to random code, that I don't know which parts of the other code actually matters for me. How should I? Here tutorials joins the game. This is sometimes true for tutorials as well, but at least the tutorial is framed. You already get some basic idea just reading the title of a tutorial.

The worst part, when comparing to Symfony is, that I have to pay for Craft and I don't get any proper documentation. As a PHP developer I'm pretty much fucked when it comes to documentation.

@brandonkelly

This comment has been minimized.

Copy link
Member

brandonkelly commented Dec 5, 2018

Sorry you’re frustrated. Craft is a Yii application that does things mostly in-line with how Yii works, so reading Yii’s docs is a good starting point. Not sure there’s much benefit to us duplicating them.

Elements are a Craft-specific concept, so we have documented that on the Element Types page. You can also see an example of how to save an entry (one of the built-in element types) from the craft\services\Elements::saveElement() API reference.

Closing this now because “the docs suck” is too broad for us to address. If you have specific suggestions, please post them as individual issues for us to consider. (And if you could tone it down a bit, we’d appreciate it.)

@TheFox

This comment has been minimized.

Copy link
Author

TheFox commented Dec 5, 2018

Yes, my specific suggestion is that you start writing more PHP tutorials for each part of Craft and Craft Commerce. Not copy & pasting from Yii, but more Craft specific things. Not only the documentation for frontend.

@brandonkelly

This comment has been minimized.

Copy link
Member

brandonkelly commented Dec 5, 2018

We do. The entire Extending Craft section of the docs is specifically for PHP development. It’s linked to from the bottom of the main docs nav.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.