Practical Tutorial

I believe that we need to have a good tutorial for the newcomers that describes the practical process of developing a web app using Yii 2.

I’m thinking of Larry Ullman’s Learning Yii Series and The Yii Blog Tutorial. Don’t you think that we have to have the Yii 2 versions of them?

The definitive guide for Yii 2 is a good thing without any doubt. But it is much larger than that of Yii 1 in its quantity … Yii 1 guide has 57 chapters, and Yii 2 guide has 101 (without counting those in the docs for yii2-gii, yii2-debug, … etc). “Read the guide”, we used to tell them, “at least twice”. :D Is it still possible with Yii 2?

Of course we have to read the guide, and also the newcomers should be recommend to do that. But in order to comprehend the guide, you must have a rough roadmap of the framework. Those who came from Yii 1 have already acquired it, but the newcomers haven’t. And they almost blindly dive into “yii2-app-advanced” :(

What do you think of it?

If it is possibile, I’ll sponsor my new book “Yii2 by example” :

I think it could be an useful starting point for beginners.

Great idea mate, I would gladly read it :]

Writing a tutorial is a huge undertaking.

just sayin’

Before undertaking the huge undertaking, I would recommend having separate ones for the basic and advanced apps prefaced by the reasons we would use one over the other. Any concept that applies to both could be included in both but the reader would know from the get go that everything they are reading applies to the version they are using.

Also, with the basic version, it would be helpful to spell out exactly how to replace the demo/demo or admin/admin hardcoded login with a sound, secure user authentication system, at the very least how to install a proven extension for this purpose.

With Yii 1, one of the most helpful things I found as a newbie was with little tidbits of how to do this and that. A smaller undertaking would be something like that, Html by example, how to do a link, a button, an image, etc.

Yes, that would be definitely great. Do you plan investing time into it? I can help with wording/structure etc.

I’m sure its been said before but I’d love to have a moderated comment system as part of the guide. Ideally it would function like the php comment system but it would be great to have ability upvote/downvote like stackoverflow.

I like the documentation for CakePHP:

Like they do, Yii could have to source on Github and accept pull requests for improvements.


We have source at GitHub and are accepting pull requests.

Same about cookbook. I’m managing it:

That is not obvious to anyone except you :)

It would be nice to have a ‘Improve this page’ or something, like on CakePHP.

It could help to engage other people more.

I also happen to think that the docs need a visual upgrade.

Heck, maybe the whole site does.

The search is still terrible.

I consider that to be a major documentation feature, to be able to find exactly what you are looking for.

But I am digressing…

I have seen cake documentation, that use git as collaborative system.

I think that it could be more direct using wiki for documentation, is not it so?

I think the Yii wiki sucks ;D

What about using Penflip or Gitbook or similar?

Thank you everyone for your feedback. :)

Agreed. I’m also just thinking about it.

I’m not sure if I will be able to spare much time on it.

But at the moment, I’d like to start so called feasibility assessment.

Yeah, it would be great, but might be of lower priority, IMO. We must have the content first.

I also think it should be source controlled on Github, just like other documents of Yii. It should be easy to be contributed.

That’s it.

What I have in mind is a turorial only for beginners that uses “yii2-app-basic” as the project template. Supposed users of “yii2-app-advanced” don’t need such a tutorial.

IMO, some beginners make wrong decision to choose "yii2-app-advanced" because of the absense of practical management system (authentication and authorization) in "basic". They might be expecting a CMS like feature in the framework, I guess. Anyway, they think that they need "backend" and jump at "advanced" even when they are using shared hosts.

Just as you have suggested, I believe the solution is to provide a sample code that describes how to implement a real-world user management system using "basic" template. It includes 1) authentication using a user table stored in db, 2) RBAC basics, and 3) an admin module that manages the users.

I’m skeptical about introducing some auth/user extension to the tutorial, needless to say introducing it to the template itself. User management can vary project to project.

With Github pages it is easy to host a Yii wiki / tutorial collection.

I wonder why the docs for Yii isn’t hosted from Github?

What? They are from GitHub:

Github pages, I mean. (gh-pages)


Before I stop hi-jacking this topic, let me show you what I mean:

That’s how Yii’s docs should look like.

The main column should not be too wide.

It is easier to scan a page that is narrow.

The navigation to the right not too intrusive.

And I like the scrollspy-like page toc to the right.

Notice the pencil link at the top?

That takes people right to the edit page for that file.

Should encourage more people to contribute.

I didn’t notice it, but looks very nice and handy.


It doesn’t really matter where it’s hosted. gh-pages or our server. It’s generated from the same source with alike script.

Suggestions about the template are good. I’d like to do it. Wish I have unlimited time to spend :)

As far as I remember, the pencil-icon was there before but people complained that it’s not really helpful for readers so it was removed. It’s still there in API docs:$aliases-detail

I think that it should be there.

It’s because it would tempt readers into being writers.

I bet that most casual readers doesn’t even know that they could contribute. ;)