Objective Complete - Mini Debriefing

tag to indicate the title of the top-level collapsible control. If an object has operations that can be performed on it, it adds the items to $this->menu, so we check that to see if it has elements in the second PHP segment. If it does, we build and display the items., Turn That DB into a Personal Mobile App

Detecting Mobile Browser – The Real Deal

Prepare for Lift Off

Engage Thrusters

Objective Complete - Mini Debriefing

Adding Issue Number to the Book Object

Engage Thrusters

Objective Complete - Mini Debriefing

Relationship Therapy

Engage Thrusters

"; foreach ($model->authors as $auth) { echo $this->renderPartial('_li', array( 'model' => $model, 'author' => $auth, )); } echo "

Objective Complete - Mini Debriefing

Creating a Mobile View Widget

Engage Thrusters

dataProvider->getData(); $owner = $this->getOwner(); foreach ($data as $i=>$item) { echo "
• "; $owner->renderPartial($this->itemView, $item); echo "
"; } ?>

" . CHtml::encode($data->notes) . "

11. Let's look at what we have now:, Turn That DB into a Personal Mobile App 12. The list looks a lot nicer now. Let's see how our mobile-optimized, all-in-one search filter works. 13. It is awesome, indeed. Try a different filter: That is some powerful stuff. 14. Let's add issue numbers to this new view. You could then use this view to see what books you have while you are shopping at the comic book store. 15. Open ch2 | Source Files | protected | views | book | _mview.php again and change it up: ' . CHtml::encode($data->title); if (!is_null($data->issue_number)) { echo ' ' . CHtml::encode($data->issue_number); } echo ''; echo '

' . CHtml::encode($data->notes) . '

'; ?>, Project 2 16. Better yet, let's change the view so that you can click on the list items to pull up the detailed view of the record. Look at what your previous changes did, then try changing it to the following code snippet: id . '">'; echo '

' . CHtml::encode($data->title); if (!is_null($data->issue_number)) { echo ' Issue: ' . CHtml::encode ($data->issue_number); } echo '

'; echo '

' . CHtml::encode($data->notes) . '

'; ?> 17. After adding the preceding code, the list will look like the following screenshot: Here is what the detailed view looks like: This is a useful set of changes., Turn That DB into a Personal Mobile App

Objective Complete - Mini Debriefing

Let's look at what we've accomplished: We created a widget for listing book objects in the mobile view and called it ListView, we made changes necessary to provide full mobile functionality to the list view for comic books, and we added a slick mobile search.

Mission Accomplished

We have learned a great deal about adding mobile functionality to a Yii project. We have seen how to include jQuery Mobile and use it in our layouts, views, and forms. We know how to make a nice mobile search. We have examples of how to add functionality and fields to an existing Yii project.,

Project 2 You Ready to go Gung HO? A Hotshot Challenge Here are some suggestions to try for yourself with this project:

f Mobile optimization Try out your mobile view with several different mobile devices. Does it work for tablets? If you find unsupported devices, extend the device identifier algorithm. Review the forms and other pages of the app and optimize them for mobile viewing. f Book form extending Add confirmation dialog to author delete action Add Ajax error handling to author add and delete actions Add Ajax confirmation flash for author add and delete actions Include publisher, illustrator, and tag fields in book form f Book view perfecting Update Book view to remove extraneous information like ID and include related information like author, illustrator, and publisher f Mobile App Expanding Expand the book list to allow you to group by publisher, illustrator, tag, and so on,

Project 3 Access All Areas – Users

and Logins In this mission, we will replace the default Yii user management and access control with a database-driven implementation, and then we will apply the access control to a new site function, and verify our work with some tests.

Mission Briefing

We will add a user table to the application database, and then generate the Yii scaffolding and customize it. We will extend the user management interface to utilize our user table fields. We will add a new feature to the site – a wish list viewer for friends and family looking for gift ideas, and then create friends and family users and give them access to the wish list. When we are done, we will be able to assign different capabilities to different users, and their menus will reflect the actions they are permitted to take. For example, guest users will only be able to read comic book entries, not add, edit, or delete, as the menu in the following screenshot demonstrates:, Access All Areas – Users and Logins

Why Is It Awesome?

The generated Yii project files include a basic access control system to help you start building your project. However, if your project requirements include providing access to a large number of users, you will soon find it helpful to include user management in your site. There are some great Yii extensions available that provide user management. These may be more or less what you want. If your project needs are unique or you would just like to take a tour through a user management implementation, this chapter will be of interest.

Your Hotshot Objectives

f Adding a User Object with CRUD f Making a User Management Interface f Storing Passwords f Activating Database User Login f Enforcing Secure Passwords f Adding User Functions – Wishlist f Configuring User Access f User Specific Menus

Mission Checklist

This project assumes that you have a web development environment prepared. If you do not have one, the tasks in Project 1, Develop a Comic Book Database, will guide you through setting one up. In order to work this project, you will need to set up the project files that have been provided with the book. Refer to the Preface of the book for instructions on downloading these files. The files for this project include a Yii project directory with a database schema. To prepare for the project, carry out the following steps replacing the username lomeara with your own username: 1. Copy the project files into your working directory. cp –r ~/Downloads/project_files/Chapter\ 3/project_files ~/projects/ch3 2. Make the directories that Yii uses web writeable. cd ~/projects/ch3/ sudo chown -R lomeara:www-data protected/runtime assets protected/models protected/controllers protected/views 3. If you have a link for a previous project, remove it from the webroot directory. rm /opt/lampp/htdocs/cddb 4. Create a link in the webroot directory to the copied directory. cd /opt/lampp/htdocs sudo ln -s ~/projects/ch3 cbdb, Project 3 5. Import the project into NetBeans (remember to set the project URL to http://localhost/cbdb) and configure for Yii development with PHPUnit. 6. Create a database named cbdb and load the database schema (~/projects/ch3/ protected/data/schema.sql) into it. 7. If you are not using the XAMPP stack or if your access to MySQL is password protected, you should review and update the Yii configuration file (in NetBeans it is ch3/Source Files/protected/config/main.php).

Adding a User Object with CRUD

As a foundation for our user management system, we will add a User table to the database and then use Gii to build a quick functional interface.

Engage Thrusters

1. Let's set the first building block by adding a User table containing the following information: A username Password hash Reference to a person entry for first name and last name In NetBeans, open a SQL Command window for the cbdb database and run the following command: CREATE TABLE 'user' ( 'id' int(10) unsigned NOT NULL AUTO_INCREMENT, 'username' varchar(20) NOT NULL, 'pwd_hash' char(34) NOT NULL, 'person_id' int(10) unsigned NOT NULL, PRIMARY KEY ('id'), UNIQUE KEY 'username' ('username'), CONSTRAINT 'userperson_ibfk_2' FOREIGN KEY ('person_id') REFERENCES 'person' ('id') ON DELETE

CASCADE

) ENGINE=InnoDB; 2. Open a web browser to the Gii URL http://localhost/cbdb/index.php/gii (the password configured in the sample code is yiibook) and use Gii to generate a model from the user table. Refer to the Generating an Application Scaffold section in Project 1, Develop a Comic Book Database, for a more detailed description of how to use Gii., Access All Areas – Users and Logins 3. Then, use Gii to generate CRUD from the user model. 4. Back in NetBeans, add a link to the user index in your site's logged in menu (ch3 | Source Files | protected | views | layouts | main.php). It should look like this: } else { $this->widget('zii.widgets.CMenu',array( 'activeCssClass' => 'active', 'activateParents' => true, 'items'=>array( array('label'=>'Home', 'url'=>array('/site/index')), array('label'=>'Comic Books', 'url'=>array('/book'), 'items' => array( array('label'=>'Publishers', 'url'=>array('/publisher')), ) ), array('label'=>'Users', 'url'=>array('/user/index')), array('label'=>'Logout ('.Yii::app()->user- >name.')', 'url'=>array('/site/logout')) ), )); } ?> 5. Right-click on the project name, run the site, and log in with the default username and password (admin/admin). You will see a menu that includes a link named Users. 6. If you click on the Users link in the menu and then click on Create User, you will see a pretty awful-looking user-creation screen. We are going to fix that. First, we will update the user form to include fields for first name, last name, password, and repeat password. Edit ch3 | Source Files | protected | views | user | _form.php and add those fields. 7. Start by changing all instances of $model to $user. Then, add a call to errorSummary on the person data under the errorSummary call on user. errorSummary($user); ?> errorSummary($person); ?>, Project 3 8. Add rows for first name and last name at the beginning of the form.
labelEx($person,'fname'); ?> textField($person,'fname',array ('size'=>20,'maxlength'=>20)); ?> error($person,'fname'); ?>
labelEx($person,'lname'); ?> textField($person,'lname',array ('size'=>20,'maxlength'=>20)); ?> error($person,'lname'); ?>
9. Replace the pwd_hash row with the following two rows:
labelEx($user,'password'); ?> passwordField($user,'password',array ('size'=>20,'maxlength'=>64)); ?> error($user,'password'); ?>
labelEx($user,'password_repeat'); ?> passwordField($user,'password_repeat',array ('size'=>20,'maxlength'=>64)); ?> error($user,'password_repeat'); ?>
10. Finally, remove the row for person_id. 11. These changes are going to completely break the User create/update form for the time being. We want to capture the password data and ultimately make a hash out of it to store securely in the database. To collect the form inputs, we will add password fields to the User model that do not correspond to values in the database. Edit the User model ch3 | Source Files | protected | models | User.php and add two public variables to the class: class User extends CActiveRecord { public $password; public $password_repeat;, Access All Areas – Users and Logins 12. In the same User model file, modify the attribute labels function to include labels for the new password fields. public function attributeLabels() { return array( 'id' => 'ID', 'username' => 'Username', 'password' => 'Password', 'password_repeat' => 'Password Repeat' ); } 13. In the same User model file, update the rules function with the following rules: Require username Limit length of username and password Compare password with password repeat Accept only safe values for username and password We will come back to this and improve it, but for now, it should look like the following: public function rules() { // NOTE: you should only define rules for those attributes //that will receive user inputs. return array( array('username', 'required'), array('username', 'length', 'max'=>20), array('password', 'length', 'max'=>32), array('password', 'compare'), array('password_repeat', 'safe'), ); } 14. In order to store the user's first and last name, we must change the Create action in the User controller ch3 | Source Files | protected | controllers | UserController. php to create a Person object in addition to a User object., Project 3 Change the variable name $model to $user, and add an instance of the Person model. public function actionCreate() { $user=new User; $person=new Person; // Uncomment the following line if AJAX validation is //needed // $this->performAjaxValidation($user); if(isset($_POST['User'])) { $user->attributes=$_POST['User']; if($user->save()) $this->redirect(array('view','id'=>$user->id)); } $this->render('create',array( 'user'=>$user, 'person'=>$person, )); } 15. Don't reload the create user page yet. First, update the last line of the User Create view ch3 | Source Files | protected | views | user | create.php to send a User object and a Person object. renderPartial('_form', array('user'=>$user, 'person' =>$person)); ?> 16. Make a change to the attributeLabels function in the Person model (ch3 | Source Files | protected | models | Person.php) to display clearer labels for first name and last name. public function attributeLabels() { return array( 'id' => 'ID', 'fname' => 'First Name', 'lname' => 'Last Name', ); }, Access All Areas – Users and Logins The resulting user form should look like this: 17. Looks pretty good, but if you try to submit the form, you will receive an error. To fix this, we will change the User Create action in the User controller ch3 | Source Files | protected | controllers | UserController.php to check and save both User and Person data. if(isset($_POST['User'], $_POST['Person'])) { $person->attributes=$_POST['Person']; if($person->save()) { $user->attributes=$_POST['User']; $user->person_id = $person->id; if($user->save()) $this->redirect(array('view','id'=>$user->id)); } } 18. Great! Now you can create users, but if you try to edit a user entry, you see another error. This fix will require a couple of more changes. First, in the user controller ch3 | Source Files | protected | controllers | UserController.php, change the loadModel function to load the user model with its related person information: $model=User::model() ->with('person') ->findByPk((int)$id);, Project 3 19. Next, in the same file, change the actionUpdate function. Add a call to save the person data, if the user save succeeds: if($model->save()) { $model->person->attributes=$_POST['Person']; $model->person->save(); $this->redirect(array('view','id'=>$model->id)); } 20. Then, in the user update view ch3 | Source Files | protected | views | user | update.php, add the person information to the form render. renderPartial('_form', array('user'=>$model, 'person' => $model->person)); ?> 21. One more piece of user management housekeeping; try deleting a user. Look in the database for the user and the person info. Oops. Didn't clean up after itself, did it? Update the User controller ch3 | Source Files | protected | controllers | UserController.php once again. Change the call to delete in the User delete action: $this->loadModel($id)->person->delete();

Objective Complete - Mini Debriefing

We have added a new object, User, to our site, and associated it with the Person object to capture the user's first and last name. Gii helped us get the basic structure of our user management function in place, and then we altered the model, view, and controller to bring the pieces together.

Making a User Management Interface

The default Yii object index provides a nice summary listing of the user entries, but for many applications, it is more efficient to have a quick search capability. For this, Yii provides an additional "admin" view. We are going to completely replace the default listing with the admin view and update the scaffold view with a better integration of User with Person information for searching and sorting.

Engage Thrusters

1. Delete the file ch3 | Source Files | protected | views | user | index.php. 2. Rename the file ch3 | Source Files | protected | views | user | admin.php to index.php. 3. In the files create.php, update.php, and view.php in ch3 | Source Files | protected | views | user, remove the following line from the menu array: array('label'=>'Manage User', 'url'=>array('admin')),, Access All Areas – Users and Logins 4. In the User controller ch3 | Source Files | protected | controllers | UserController. php, delete the function named actionIndex. 5. Also in the User controller, remove the admin accessRule for the admin action. The admin accessRule should look like the following: array('allow', // allow admin user to perform 'delete' actions 'actions'=>array('delete'), 'users'=>array('admin'), ), Also, change the redirect in the delete action to send to the index. $this->redirect(isset($_POST['returnUrl']) ? $_POST['returnUrl'] : array('index')); 6. In the same file, rename the function actionAdmin to actionIndex, and change the call to render in the newly renamed actionIndex function to render to index instead of admin. Now, if you click on the Users link in the menu, you will see a user management grid, instead of a list of user entries. However, the information in the grid could be more useful., Project 3 7. Edit the new user index ch3 | Source Files | protected | views | user | index.php. Remove the unnecessary column values id, pwd_hash, and person_id from the view. Add the columns we do want to see, namely first name and last name. These fields come from a related object, so their entries will look a little different. The file should look as follows: 'columns'=>array( 'username', array( 'name' => 'person_fname', 'header' => 'First Name', 'value' => '$data->person->fname', ), array( 'name' => 'person_lname', 'header' => 'Last Name', 'value' => '$data->person->lname', ), array( 'class'=>'CButtonColumn', ), ), The entries for first name and last name include: A name value, which is the name of the search variable A header value, which is the column label A data value, which is the data field that will populate the column output 8. Edit the user model ch3 | Source Files | protected | models | User.php, and add public variables to catch the search fields person_fname and person_lname: class User extends CActiveRecord { public $password; public $password_repeat; public $person_fname; public $person_lname;, Access All Areas – Users and Logins 9. In the same file, add a search field entry to the rules function with username, person_fname, and person_lname: public function rules() { // NOTE: you should only define rules for //those attributes that will receive user inputs. return array( array('username', 'required'), array('username', 'length', 'max'=>20), array('password', 'length', 'max'=>32), array('password', 'compare'), array('password_repeat', 'safe'), array('username, person_fname, person_lname', 'safe', 'on'=>'search'), ); } 10. The search function will require the most changes. We will need to remove the unused fields (id, pwd_hash, and person_id), update the username field to indicate that it is from the base model, add the person relationship to the criteria, and add comparisons of the related fields (first and last name). public function search() { $criteria=new CDbCriteria; $criteria->compare('t.username',$this- >username,true); $criteria->compare('person.fname',$this- >person_fname,true); $criteria->compare('person.lname',$this- >person_lname,true); $criteria->with = array('person'); return new CActiveDataProvider($this, array( 'criteria'=>$criteria, )); }, Project 3 Now the grid will display all of the fields perfectly. However, you can only sort on the username column. 11. In the User model search function, add a sort object with first name and last name fields and include it in the data provider to activate sort on the first name and last name columns. $sort = new CSort; $sort->attributes = array( 'person_fname' => array( 'asc' => 'person.fname', 'desc' => 'person.fname DESC', ), 'person_lname' => array( 'asc' => 'person.lname', 'desc' => 'person.lname DESC', ), '*', ); return new CActiveDataProvider($this, array( 'criteria'=>$criteria, 'sort' => $sort, ));, Access All Areas – Users and Logins 12. Oh! One more thing. Have you clicked on the Advanced Search link yet? That doesn't look great. We can clean up the advanced search form ch3 | Source Files | protected | views | users | _search.php. Remove ID and password hash fields, and add first name and last name fields.
label($model,'username'); ?> textField($model,'username',array ('size'=>20,'maxlength'=>20)); ?>
label($model,'First Name'); ?> textField($model,'person_fname',array ('size'=>10,'maxlength'=>10)); ?>
label($model,'Last Name'); ?> textField($model,'person_lname',array ('size'=>10,'maxlength'=>10)); ?>
, Project 3 Now it looks good! 13. The last view we will change is named View. Edit ch3 | Source Files | protected | views | users | view.php. Delete id, pwd_hash, and person_id from the attributes array. Add person_fname and person_lname to the list. array( 'name' => 'person_fname', 'header' => 'First Name', 'value' => $model->person->fname, ), array( 'name' => 'person_lname', 'header' => 'Last Name', 'value' => $model->person->lname, ),

Objective Complete - Mini Debriefing

We have removed the original user index and replaced it with the admin page that Yii provides, but modified so that the information is relevant, searchable, and sortable., Access All Areas – Users and Logins

Classified Intel

We could make the index even more compact by moving the Create User link into the page, perhaps incorporating it into the grid, and removing the side menu, because the only other link is back to the index, and changing the layout to one column, instead of two.

Storing Passwords

In this task, we will add a hashing function and store the hashed password values in the database.

Engage Thrusters

1. We have a nice user management interface, but if you open a SQL command window and query the user table, you will see that the password field for each user is empty. select * from user; 2. We need to store the password, and in order to do that, we need to make a function to hash passwords. We will implement this function in the User model and do it in a rather simplistic way, using the crypt library that comes with PHP and providing no salt value, so that it is randomly generated by the library. You can replace this function with your own preferred method of hashing. public function hash($value) { return crypt($value); }, Project 3 3. Next, we need to call the encryption function whenever we store a password – on create and on update – so we will overload the beforeSave function to do the hashing. Add the following function to the User model: protected function beforeSave() { if (parent::beforeSave()) $this->pwd_hash = $this->hash($this->password); return true; } return false; } Now, if you add or update a user and look at the user table, you will see a hash value in your user entry. 4. In preparation for logging in, let's go ahead and add a function to check a password value against the hashed value. public function check($value) { $new_hash = crypt($value, $this->pwd_hash); if ($new_hash == $this->pwd_hash) { return true; } return false; }, Access All Areas – Users and Logins

Objective Complete - Mini Debriefing

We have added a hashing function to our User model to perform one way hashing on password values, then applied the hashing function to password values after they have been validated. We prepared for the next step by adding a hash check function to the User model as well. At this point, the hashing will not be applied to the login, but in the next task, we will activate it.

Activating Database User Login

In this task, we will convert the login action from the default authentication system provided by Yii to the authentication we have prepared in the previous tasks.

Prepare for Lift Off

We are about to cut over to a new authentication system. Before we do, be sure to create a user for yourself with a password that you know! If you haven't already, log in as admin/admin, go to the Users screen, create a user named admin with a password test. You can give this user whatever first and last name you like. We are about to use it to log in.

Engage Thrusters

1. Edit the UserIdentity file ch3 | Source Files | protected | components | UserIdentity.php and replace the contents of the authenticate function with the following: $user = User::model() ->findByAttributes(array( 'username' => $this->username )); if($user===null) $this->errorCode=self::ERROR_USERNAME_INVALID; else if ($user->check($this->password)) { $this->errorCode=self::ERROR_NONE; } else $this->errorCode=self::ERROR_PASSWORD_INVALID; return !$this->errorCode;, Project 3 Now, the authenticate function will look in the database for the provided username. If that user is found, it will check the provided password against the user's password hash. 2. Give it a try. Log out (if you are logged in), and try logging back in as admin/admin. Now log in with the admin user we created earlier (admin/test). 3. Before we forget, edit the login view ch3 | Source Files | protected | views | site | login.php and remove the demo and admin user hint.

Objective Complete - Mini Debriefing

Now, instead of having to edit the UserIdentity file, and hardcode in another user/ password combination, you can use the web interface to create as many users as you like. If there is a user who no longer needs access to the system, you can delete the user and his/ her credentials will no longer work. This approach will be much easier to maintain.

Enforcing Secure Passwords

Looking again at user creation, we can see another problem. You can create a user with no password. That is not so bad, because the login form requires a password. If your user has no password, he will not be able to login, but what about the quality of the passwords? If you try to enter a one-character password, no problem, you can do it. This might be ok if you are the only person creating users and entering passwords. You can be careful to give your users passwords that are difficult to guess. You can devise and enforce your own password strength requirements, but typically, sooner or later, you are going to let your users set their own passwords. When this happens, you will want to enforce some checking to make sure the passwords your users set are difficult to guess. Otherwise, your users and your site are vulnerable to password cracking., Access All Areas – Users and Logins You can use this basic pattern for applying a password strength scheme and implement your own password strength requirements that are appropriate to your site. We will go with a basic requirement of a minimum length of eight characters, including at least one capital character, at least one number, and at least one non-alphanumeric character. This pattern is also useful for implementing any custom validation rule.

Engage Thrusters

1. Open the user model file for edit (ch3 | Source Files | protected | models | User.php). 2. Add a function named passwordStrengthOk as follows: public function passwordStrengthOk($attribute, $params) { // default to true $valid = true; // at least one number $valid = $valid && preg_match ('/.*[\d].*/', $this->$attribute); // at least one non-word character $valid = $valid && preg_match ('/.*[\W].*/', $this->$attribute); // at least one capital letter $valid = $valid && preg_match ('/.*[A-Z].*/', $this->$attribute); if (!$valid) $this->addError($attribute, "Does not meet password requirements."); return $valid; } 3. Add two new rules to the validation array: Require a unique username. Add the new rule we created, passwordStrengthOk and change one old rule. Add a check for minimum password length of 8 to the password length requirements. return array( array('username', 'required'), array('username', 'unique'),, Project 3 array('password, password_repeat', 'required'), array('username', 'length', 'min' => 3, 'max'=>20), array('password', 'length', 'min' => 8, 'max'=>32), array('password', 'compare', 'compareAttribute' => 'password_repeat'), array('password', 'passwordStrengthOk'), array('username, password, password_repeat', 'safe'), array('username, person_fname, person_lname', 'safe', 'on'=>'search'), ); 4. But what if we want to update something about the user, such as change the username, and not enter a new password? To do this, we will use a scenario. First, update the rules that apply to passwords and add the scenario parameter, so that the rules are only applied when the scenario is in play. return array( array('username', 'required'), array('username', 'unique'), array('password, password_repeat', 'required', 'on' => 'passwordset'), array('username', 'length', 'min' => 3, 'max'=>20), array('password', 'length', 'min' => 8, 'max'=>32, 'on' => 'passwordset'), array('password', 'compare', 'compareAttribute' => 'password_repeat'), array('password', 'passwordStrengthOk', 'on' => 'passwordset'), array('username, password, password_repeat', 'safe'), array('username, person_fname, person_lname', 'safe', 'on'=>'search'), ); i. Then, in the User controller, activate the passwordset scenario whenever we want the passwordset rules to apply. In the Create function, we always want the scenario to apply, so pass it to the model constructor at the start. $user=new User('passwordset'); ii. In the Update function, we only want to apply the scenario when a password field has been entered, so set the scenario on the model conditionally. After the attributes are gathered from the form, if the password or password_repeat value has been set, apply the scenario. $model->attributes=$_POST['User']; if ($model->password || $model->password_repeat) $model->scenario = 'passwordset';, Access All Areas – Users and Logins 5. Let's make sure we did all of that correctly by making and running a functional test. 6. First, we will augment our testing setup by downloading the Selenium standalone server from http://seleniumhq.org/. 7. Then, update the phpunit config to define the browsers that you will test against. In our example, we will test against Firefox (of course, you must have Firefox installed to do this). Add the following section to ch3 | Test Files | phpunit.xml: 8. Open ch3 | Test Files | WebTestCase.php and change TEST_BASE_URL to the URL of our site. define('TEST_BASE_URL', 'http://localhost/cbdb/'); 9. Start the Selenium standalone server by opening a terminal window, changing to the directory where you downloaded the standalone server, and running the following command (updated to include the version of the server you downloaded): java -jar selenium-server-standalone-.jar 10. Navigate to ch3 | Test Files. 11. Right-click on the folder named functional and select New | PHP File. 12. Enter UserTest for the filename and click on Finish. 13. Input the following contents into the new test file. start(); $this->open(''); // login $this->clickAndWait('link=Login'); $this->type('name=LoginForm[username]','admin'); $this->click("//input[@value='Login']"); $this->waitForTextPresent ('Password cannot be blank.'); $this->type('name=LoginForm[password]','test'); $this->clickAndWait("//input[@value='Login']");, Project 3 // go to users page $this->clickAndWait('link=Users'); } public function testPasswordMatch() { $this->clickAndWait('link=Create User'); $this->type('name=Person[fname]','Func'); $this->type('name=Person[lname]','Test'); $this->type('name=User[username]','functest'); $this->type('name=User[password]','functest'); $this->type('name=User [password_repeat]','nomatchpass'); $this->clickAndWait("//input[@value='Create']"); $this->assertTextPresent ('Password must be repeated exactly.'); $this->assertTextPresent ('Does not meet password requirements.'); $this->assertTextNotPresent ('Password is too short (minimum is 8 characters).'); } public function testPasswordTooShort() { $this->clickAndWait('link=Create User'); $this->type('name=Person[fname]','Func'); $this->type('name=Person[lname]','Test'); $this->type('name=User[username]','functest'); $this->type('name=User[password]','moo'); $this->type('name=User[password_repeat]','moo'); $this->clickAndWait("//input[@value='Create']"); $this->assertTextPresent ('Password is too short (minimum is 8 characters).'); $this->assertTextPresent ('Does not meet password requirements.'); $this->assertTextNotPresent ('Password must be repeated exactly.'); } public function testGoodPassword() { $this->clickAndWait('link=Create User'); $this->type('name=Person[fname]','Func'); $this->type('name=Person[lname]','Test'); $this->type('name=User[username]','functest');, Access All Areas – Users and Logins $this->type('name=User[password]','m00!Isay'); $this->type('name=User[password_repeat]','m00!Isay'); $this->clickAndWait("//input[@value='Create']"); $this->assertTextPresent('View User'); } public function testDeleteUser() { $this->clickAndWait ("xpath=(//img[@alt=\"View\"])[2]"); $this->clickAndWait('link=Delete User'); $this->assertConfirmation ('Are you sure you want to delete this item?'); $this->assertTextNotPresent('functest'); } } ?> 14. Be sure to save the new contents. Then, while viewing the new test file in NetBeans, press Shift + F6 to run the functional test. You should see Selenium and Firefox windows flash on your screen as the tests run. The tests should complete successfully and confirm that the password validation rules are applied correctly.

Objective Complete - Mini Debriefing

In order to improve our site security, we have added a custom validation rule to the user model. The new rule implements a password strength requirement that we defined, but you can replace this with your own custom definition or an existing library, such as CrackLib. To make sure your new rule is being enforced correctly, and to demonstrate functional testing with Selenium, we added a set of Selenium tests.

Adding User Functions – Wishlist

To demonstrate access control, we will create a new function for users of our site to show them our comic book wishlist. When a special occasion is coming up, your friends and family will be able to log in and view your wishlist to get gift ideas., Project 3

Engage Thrusters

1. Start by adding a new table to the database as follows: CREATE TABLE 'wish' ( 'id' int(10) unsigned NOT NULL AUTO_INCREMENT, 'title' varchar(256) NOT NULL, 'issue_number' varchar(10) DEFAULT NULL, 'type_id' int(10) unsigned DEFAULT NULL, 'publication_date' date DEFAULT NULL, 'store_link' varchar(255) DEFAULT NULL, 'notes' text DEFAULT NULL, 'got_it' int(10) unsigned DEFAULT NULL, PRIMARY KEY ('id'), KEY 'type_id' ('type_id'), KEY 'got_it' ('got_it'), CONSTRAINT 'wish_ibfk_1' FOREIGN KEY ('type_id') REFERENCES 'type' ('id'), CONSTRAINT 'wish_ibfk_2' FOREIGN KEY ('got_it') REFERENCES 'user' ('id') ) ENGINE=InnoDB; 2. Add join tables for author, illustrator, and publisher as follows: CREATE TABLE 'wishauthor' ( 'wish_id' int(10) unsigned NOT NULL, 'author_id' int(10) unsigned NOT NULL, PRIMARY KEY ('wish_id','author_id'), KEY 'author_id' ('author_id'), CONSTRAINT 'wishauthor_ibfk_1' FOREIGN KEY ('wish_id') REFERENCES 'wish' ('id') ON DELETE CASCADE, CONSTRAINT 'wishauthor_ibfk_2' FOREIGN KEY ('author_id') REFERENCES 'person' ('id') ) ENGINE=InnoDB; CREATE TABLE 'wishillustrator' ( 'wish_id' int(10) unsigned NOT NULL, 'illustrator_id' int(10) unsigned NOT NULL, PRIMARY KEY ('wish_id','illustrator_id'), KEY 'illustrator_id' ('illustrator_id'), CONSTRAINT 'wishillustrator_ibfk_1' FOREIGN KEY ('wish_id') REFERENCES 'wish' ('id') ON DELETE CASCADE,, Access All Areas – Users and Logins CONSTRAINT 'wishillustrator_ibfk_2' FOREIGN KEY ('illustrator_id') REFERENCES 'person' ('id') ) ENGINE=InnoDB; CREATE TABLE 'wishpublisher' ( 'wish_id' int(10) unsigned NOT NULL, 'publisher_id' int(10) unsigned NOT NULL, PRIMARY KEY ('wish_id','publisher_id'), KEY 'publisher_id' ('publisher_id'), CONSTRAINT 'wishpublisher_ibfk_1' FOREIGN KEY ('wish_id') REFERENCES 'wish' ('id') ON DELETE CASCADE, CONSTRAINT 'wishpublisher_ibfk_2' FOREIGN KEY ('publisher_id') REFERENCES 'publisher' ('id') ) ENGINE=InnoDB; 3. The new tables and their relationships look like the following: 4. Use Gii to generate a model and CRUD from the wish table, and models for all of the join tables (wishauthor, wishillustrator, and wishpublisher)., Project 3 5. Add a new item to the Comic Book menu in ch3 | Source Files | protected | views | layouts | main.php as follows: array( 'label'=>'Comic Books', 'url'=>array('/book'), 'items' => array( array('label'=>'Publishers', 'url'=>array('/publisher')), array('label'=>'WishList', 'url'=>array('/wish/index')), ) ), Now, when you expand the Comic Books menu, you will see an entry for WishList, as follows: 6. Since wish has a lot of the same fields as book, we copied ch3 | Source Files | protected | views | book | _form.php to the wish view folder, removed the unnecessary fields value, price, signed, grade, and bagged, and added the unique wish field, store_link. The resulting file ch3 | Source Files | protected | views | wish | _form.php can be found in the chapter files ch3 | Source Files | example | wish | _form.php. The form will not work until we make a few changes. 7. We have already pulled the author functions that you might want to use out of the Book controller and put them in a base controller that the Book controller is using. To access the author functions in the Wish controller, change the base class. class WishController extends BController i. Delete the update action from the Wish controller and change the generated create action to the following: public function actionCreate() { $model=new Wish; $this->create($model); }, Access All Areas – Users and Logins ii. Create a function to record the association between a wish and an author. protected function saveAssociation($model, $author) { // record wish/author association $wa = new WishAuthor; $wa->wish_id = $model->id; $wa->author_id = $author->id; $wa->save(); } iii. Add removeAuthor and createAuthor to the allowed actions for users. (We will adjust the permissions in a later task.) array('allow', // allow authenticated user to perform 'create' and 'update' actions 'actions'=>array('create','update', 'removeAuthor','createAuthor'), 'users'=>array('@'), ), 8. Add support for authors to the Wish model ch3 | Source Files | protected | models | Wish.php. Start by adding the following functions: /* * assign this author to this wish */ public function addAuthor($author) { $wishauthor = new WishAuthor(); $author->save(); $wishauthor->wish_id = $this->id; $wishauthor->author_id = $author->id; $wishauthor->save(); } /* * remove an author association from wish */ public function removeAuthor($author_id) { $pk = array('wish_id'=>$this->id, 'author_id' => $author_id); WishAuthor::model()->deleteByPk($pk);, Project 3 Then, add the following two relations: 'authors' => array(self::MANY_MANY, 'Person', 'wishauthor(author_id, wish_id)', 'index'=>'id'), 'wishauthors' => array(self::HAS_MANY, 'WishAuthor', 'wish_id', 'index' => 'author_id'), 9. Add the author variable to the call to renderPartial in the Wish create and update views, ch3 | Source Files | protected | views | wish | create.php and ch3 | Source Files | protected | views | wish | update.php respectively. In both files, the call will look like the following: renderPartial('_form', array('model'=>$model, 'author'=>$author)); ?> Also include the author add JavaScript at the beginning of both files: Yii::app()->clientScript->registerScriptFile( Yii::app()->request->baseUrl . '/js/book_form_ajax.js' );

Objective Complete - Mini Debriefing

In this task, we have created another object, a wish. This object benefitted from its similarity to the book object and the work we had already done to associate books to authors. We will use this object to demonstrate configuring different capabilities for different users.

Configuring User Access

There is more than one way to define user access. One is the file-based method we replaced in this chapter. Another method is role-based and it is demonstrated in another project. For this project, we will define user-based access to the wishlist function, and we will provide two levels of access: f Admin – our own login, which will be used to create and maintain the wishlist f Everyone else – for our friends and family who want to view the wishlist and claim items that they have got for us, Access All Areas – Users and Logins

Prepare for Lift Off

To perform a cursory check (as opposed to a comprehensive suite of unit tests) of the changes we are about to make, you will need to have the ability to log in as two different users with different levels of access. We already have an admin user, which is our own login for creating and maintaining the wishlist. Create another account with username guest and password Gu3st!!! to test guest access. For our development and testing, this user represents all of our other users who will have the ability to view the wishlist and claim items they have got for us (so we don't get duplicate presents). Run the following MySQL commands to insert some wish data into your database: INSERT INTO 'wish' VALUES (1,'Moebius\' Airtight Garage Vol.1','1',1,'0000-00-00','http://www.amazon.com/ Moebius-Airtight-Garage-Vol-1-No/dp/B00178YGFE/ ref=sr_1_3?s=books&ie=UTF8&qid=1339476850&sr=1- 3','',NULL),(2,'The Squiddy Avenger','1',1,'2012-06- 21','www.amazon.com','',NULL),(3,'another great title','',1,'2012-06-21','','',NULL); INSERT INTO 'person' VALUES (226,'Jean','Giraud'),(227,'John','Smith'); INSERT INTO 'wishauthor' VALUES (1,226),(2,227);

Engage Thrusters

As administrators, we pretty much have all the capabilities we need already. In fact, we may want to limit one thing. What good is our wishlist if we lose the surprise by seeing what our friends have got for us? Of course, you can cut out the parts that hide the information from admin or leave them in and find other ways to peek at your gifts in the database. Let's start by limiting our guests' access, and then update the wishlist view to achieve the desired effect. We are going to customize the users' menu view in a later task, so that for now, when we are logged in as a guest, we can easily click all options and see what we can and cannot do. 1. Log in as guest/Gu3st!!!. 2. From the menu, you can see and access the user index. Let's eliminate that option for our guests. For now, only the administrator will be able to view, create, update, or delete users. Open the user controller ch3 | Source Files | protected | controllers | UserController.php and consolidate all of the actions into the allowed array for the admin user. When you are done, accessRules should look as follows: public function accessRules() {, Project 3 return array( array('allow', // allow admin user to perform 'delete' actions 'actions'=>array('index', 'view', 'create', 'update', 'delete'), 'users'=>array('admin'), ), array('deny', // deny all users 'users'=>array('*'), ), ); } 3. Now, click on Users in the menu and you should see an error message as shown in the following screenshot: 4. If you want to log out of guest and log back in as admin at this point to make sure you still have user management access, we don't blame you. Go ahead. Check it out. Then, log back in as guest to continue. 5. Guests really don't need to view publishers either. So make the same change to accessRules in ch3 | Source Files | protected | controllers | PublisherController.php., Access All Areas – Users and Logins 6. We want to share our list of books with our users, but not anonymous strangers. Also we don't want guests changing anything. To accomplish this, make the following changes to the book controller. Move access to index and view down to authenticated users. Move access to create, update, removeAuthor, and createAuthor down to admin user. Remove the all users section. The result should look as follows: public function accessRules() { return array( array('allow', // allow authenticated user to perform 'index' and 'view' actions 'actions'=>array('index','view'), 'users'=>array('@'), ), array('allow', // allow admin user to perform 'create' 'update' 'admin' and 'delete' actions 'actions'=>array('create','update', 'removeAuthor','createAuthor','admin','delete'), 'users'=>array('admin'), ), array('deny', // deny all users 'users'=>array('*'), ), ); } 7. Wishlist is similar to the book list in the previous step, but we do want guests to be able to claim items from the list. Let's start by replacing the access rules in the Wish controller with the access rules we just made for Books. Now we will make one small side-track to make our wishlist look nice for our guests. 8. We created a field for a store link to make it convenient for our friends to click right on an item we want and purchase it. But right now that URL displays as un-clickable text. Edit ch3 | Source Files | protected | views | wish | _view.php and make this change to the store_link field to make it clickable from the index. getAttributeLabel('store_link')); ?>: Purchase
, Project 3 9. We added target="_blank" to the link so that it will open in another browser window. That way our users can remain in our site. 10. Our users don't need to see ID values, and for that matter, neither do we. But they may want to click an item and read more about it. To that end, remove the ID field, and update the title field to be the link to the item. getAttributeLabel('title')); ?>: title), array('view', 'id'=>$data->id)); ?>
11. Now, let's clean up the individual wish view ch3 | Source Files | protected | views | wish | view.php. Replace the page title with the wish title.

Wish: title);?>

12. Remove id from the detail view attribute list, and change the store link to pass an attribute array, including a name, type=raw, and the defined link. We also want to display the type value as text instead of a number. The final attributes of the detail view should look as follows: 'attributes'=>array( 'title', 'issue_number', array( 'name' => 'type', 'value' => $model->type->name, ), 'publication_date', array( 'name' => 'store link', 'type' => "raw", 'value' => "store_link . "\" target=\"_blank\">Purchase", ), 'notes', 'got_it', ),, Access All Areas – Users and Logins The resulting wish details screen will look like the following: 13. Now that the index and view are looking pretty nice for our guests, we should limit the wish list items so that a user only sees unclaimed items or items that user has claimed. First, we must extend the UserIdentity class to store and return the user's ID and name. i. Open ch3 | Source Files | protected | components | UserIdentity.php and add private fields named _id and _username to the class. private $_id; private $_username; ii. Add functions to return the values. public function getName() { return $this->_username; } public function getId() { return $this->_id; }, Project 3 iii. Set the value when we have a successful authentication. if ($user->check($this->password)) { $this->_id = $user->id; $this->_username = $user->username; $this->errorCode=self::ERROR_NONE; } 14. Now that the user identity class can return the current user's ID and username, we can update the Index action in the Wish controller to limit the wish list, if the user is not admin. public function actionIndex() { if(Yii::app()->user->getName() == 'admin') { $dataProvider=new CActiveDataProvider('Wish'); } else { $dataProvider=new CActiveDataProvider ('Wish', array( 'criteria' => array( 'condition' => 'got_it is null OR ' . 'got_it=' . Yii::app()->user->getId(), ) )); $this->render('index',array( 'dataProvider'=>$dataProvider, )); } If you are currently logged in as a guest and try to access this page, you will see an error message. You will need to log out and log back in as a guest in order to access the Wish index. At this point, to test our work, we logged in as admin and created a few wishes. Then we used the database Execute Command feature to set a few wish got_it values to various users, and left a few unclaimed. We logged in as each of those users to verify that we saw unclaimed wishes and the user's claimed wishes. We also logged in as admin to verify that admin sees the complete list. 15. The next part of the feature that we will need is the ability to claim a wish. To keep it a surprise, we are going to show this feature to users but not to admin., Access All Areas – Users and Logins Edit ch3 | Source Files | protected | views | wish | view.php and change the attribute value for the field got_it as follows: array( 'name' => 'Got It', 'value' => (Yii::app()->user->getName() != 'admin') ? $model->got_it : '' ), 16. Edit ch3 | Source Files | protected | views | wish | _view.php and add the following to display a claim/unclaim checkbox: user->getName() != 'admin') { ?> getAttributeLabel('got_it')); ?>: got_it == Yii::app()->user->getId()), array('class' => 'claim', 'url'=> Yii::app()->controller->createUrl( "claim", array("id"=>$data->id) ) ) ); ?>
The result should look like the following screenshot:, Project 3 17. To support the checkbox toggle function we are going to add Ajax to catch the checkbox click. Create a file in ch3 | Source Files | js named wish_list_ajax.js with the following contents: $(document).ready(function() { $('.claim').click(function() { $.ajax({ type: 'get', url: $(this).attr('url'), data: {"ajax" : "1"}, success: function(resp) { $("ul.authors").append(resp); }, error: function() { alert("Error claiming wish."); } }); }); }); 18. To include the script in the wish index, edit ch3 | Source Files | protected | views | wish | index.php and add the script at the beginning of the file. Yii::app()->clientScript->registerScriptFile( Yii::app()->request->baseUrl . '/js/wish_list_ajax.js' ); 19. Then, of course, we need to add the claim action itself to the Wish controller. public function actionClaim($id) { // request must be made via ajax if(isset($_GET['ajax'])) { $model=$this->loadModel($id); // if the wish was claimed by the user, toggle it //off if ($model->got_it == Yii::app()->user->getId()) { $model-> got_it = new CDbExpression('NULL'); } // if the wish was claimed by no one, toggle it on if ($model->got_it == null) { $model->got_it = Yii::app()->user->getId(); } $model->save(); } else throw new CHttpException(400,'Invalid request.'); }, Access All Areas – Users and Logins Update the access rules to include the new action, allowing authenticated users to claim wishes. array('allow', // allow authenticated user to perform 'index' and 'view' actions 'actions'=>array('index','view','claim'), 'users'=>array('@'), ),

Objective Complete - Mini Debriefing

We have used the basic access control that is provided by Yii to limit general user access for viewing the comic book list and items and the wish list and items.

User Specific Menus

In the last task, we limited user access, but we did not update the menus. The site menu provides links to objects that users do not have permission to access, and the object menus provide links to actions that users do not have authorization to take. It would be nice if we could associate the menus to the access we have already defined, so that we do not have to manually coordinate menu contents with accessRules. To do this, we created an extension to the CMenu widget.

Engage Thrusters

1. Create a new file in ch3 | Source Files | protected | components named AuthMenu.php. 2. Enter the following contents into the file: , Project 3 * @copyright Copyright © 2012 Plum Flower Software * @version 0.1 * @license New BSD Licence */ class AuthMenu extends CMenu { public function init() { $this->items = $this->filterItems($this->items); return parent::init(); } /** * Filter recursively the menu items received setting visibility true or * false according to controller/action preFilter * * @param array $items The menu items being filtered. * @return array The menu items with visibility defined by preFilter(). */ protected function filterItems(array $items){ $app = Yii::app(); foreach($items as $pos=>$item) { if(!isset($item['visible'])) { // get the url parameter if(isset($item['url']) && is_array($item['url'])) $url=$item['url'][0]; // parse the url into controller and action $parts = explode("/",$url); if ( count($parts) == 1) { $controller = $app->controller; $actionId = $parts[0]; } else { $controllerId = ucfirst($parts[1]); $actionId = count($parts) > 2 ? $parts[2] : 'index'; $controllerList = $app- >createController($controllerId); $controller = $controllerList[0]; }, Access All Areas – Users and Logins // generate a controller instance to access and //compare the rules $action = $controller->createAction($actionId); $filter = new CAccessControlFilter; $filter->setRules($controller->accessRules()); $user = $app->getUser(); $request = $app->getRequest(); $ip = $request->getUserHostAddress(); $item['visible'] = false; foreach ($filter->getRules() as $rule) { // we are making an assumption for now that all // menu items are GET actions if($rule->isUserAllowed($user, $controller, $action, $ip, 'GET') > 0) { $item['visible'] = true; break; } } } /** * If current item is visible and has sub items, loops recursively * on them. */ if(isset($item['items']) && $item['visible']) $item['items']=$this->filterItems($item['items']); $items[$pos]=$item; } return $items; } } 3. Next, consolidate the main site menu back into one widget call. Set the visible value for the Home item to true, and set the visible value for Login and Logout to conditional based on whether the user is logged into the site or not, using the isGuest command. Replace the call to CMenu in main layout file ch3 | Source Files | protected | views | layouts | main.php.
widget('application.components.AuthMenu',array( 'activeCssClass' => 'active', 'activateParents' => true, 'items'=>array( array('label'=>'Home', 'url'=>array('/site/index'), 'visible' => true), array( 'label'=>'Comic Books', 'url'=>array('/book'), 'items' => array( array('label'=>'Publishers', 'url'=>array('/publisher')), array('label'=>'WishList', 'url'=>array('/wish/index')), ) ), array('label'=>'Users', 'url'=>array('/user/index')), array('label'=>'Login', 'url'=>array('/site/login'), 'visible'=>Yii::app()->user->isGuest), array('label'=>'Logout ('.Yii::app()->user->name.')', 'url'=>array('/site/logout'), 'visible'=>!Yii::app()- >user->isGuest), ), )); ?>
The consolidated menu for admin should look the same as before, like the following screenshot:, Access All Areas – Users and Logins The menu for a guest will have fewer items, as shown in the following screenshot: 4. Also replace the call to CMenu in the two column layout ch3 | Source Files | protected | views | layouts | column2.php. $this->widget('application.components.AuthMenu', array( 'items'=>$this->menu, 'htmlOptions'=>array('class'=>'operations'), )); The action menu on the right-hand side of the screen will now display only authorized actions. For admin, the list will include all actions, as shown in the following screenshot:, Project 3 For guests, the list of authorized actions will not include Create, Update, or Delete, as shown in the following screenshot:

Objective Complete - Mini Debriefing

In the extension that we created, we iterate over the list of menu items and use context and the url parameter to determine which controller and action the menu item contains. Then we check the array in the accessRules function for the controller against the user and action to determine the visibility of the menu item.

Mission Accomplished

In this project, we have improved user management for our site by replacing the default file- based user management that Yii framework provides with database-stored users. By making this change, we get the benefit of the web interface to manage our users, instead of having to change the text in a source file. We removed the default User index and replaced it with the Yii-generated admin page, which provides Ajax record searching and quick links to view/update/delete users. We also customized this view to include support for fields from the related table, Person. As a result we can search and sort on fields from Person, as well as User. We improved site security by creating a custom validation rule that enforces some password strength requirements, and we apply this rule only when we need to change the password, not when we are making a change to an existing user. We tested the implementation of this validation rule and tried out functional testing with Selenium. We added a new function to demonstrate Yii access control settings. And we showed a way to display user-specific menus. This will get even better in the next project when we group users into roles.,

Access All Areas – Users and Logins Remember to review your security if you put this site online. You may want to review the

following considerations: f You may not want to use XAMPP for a public server f If you do use XAMPP, at the least, enable secure mode f Obtain and use an SSL certificate; require encrypted access to the login page, so that passwords are not transmitted unencrypted f Definitely disable Gii in your Yii site configuration f Also be sure to disable phpMyAdmin

You Ready to go Gung HO? A Hotshot Challenge Here are some ideas to go gung ho with user functions:

f You could expand your wishlist system to allow other users to track their wishlists. f You could extend the user object with a Boolean value to indicate active/inactive users, instead of deleting user entries. f Extend the functional tests. f Check out the Selenium Firefox extension and the Selenium IDE: PHP Formatters.

Try using them to record more functional tests.

f Replace all index views with the admin view, like we did for Users. f Add a function to transfer a wish into your book list, once you have received it.,

Project 4 Level Up! Permission Levels

In this mission, we will implement a lending function and a fine grained access control. In our experience, most projects require the ability to define permissions at a very precise level. A good example of this is providing users with the ability to edit their own account information, but not the account information of other users. In this project, we will use Yii and available extensions to construct a custom permissions system for our comic book application.

Mission Briefing

We will add a library management page for you to manage the books you share and a lend/borrow page for your friends to see books that they can borrow and request. Then, we will replace the default Yii user access with a more extensive user management system that includes roles and access levels.

Why Is It Awesome?

Almost any web application you make is going to have users with different levels of access. This project will demonstrate a method for adding users and access control to any site you build with Yii. We will also touch on some website security issues here, but encourage you to study this topic well and enhance your knowledge of security with every site you build., Level Up! Permission Levels

Your Hotshot Objectives

Here is an overview of the project steps: f Adding Admin Function – Library Management f Adding User Functions – Library f Defining Roles and Access f Adding the RBAC Extension f Adding Roles to User Management f Fine-tuning Permissions f Making History

Mission Checklist

This project assumes that you have a web development environment prepared. If you do not have one, the tasks in Project 1, Develop a Comic Book Database, will guide you through setting one up. In order to work this project, you will need to set up the project files that have been provided with the book. Refer to the Preface of the book for instructions on downloading these files. The files for this project include a Yii project directory with a database schema. To prepare for the project follow these steps, replacing the username lomeara with your own username: 1. Copy the project files into your working directory. cp –r ~/Downloads/project_files/Chapter\ 4/project_files ~/projects/ch4 2. Make the directories that Yii uses web writeable. cd ~/projects/ch4/ sudo chown -R lomeara:www-data protected/runtime assets protected/models protected/controllers protected/views 3. Create a link in the webroot directory to the copied directory. cd /opt/lampp/htdocs sudo ln -s ~/projects/ch4 cbdb 4. Import the project into NetBeans (remember to set the project URL to http://localhost/cbdb) and configure for Yii development with PHPUnit. 5. Create a database named cbdb and load the database schema (~/projects/ch4/ protected/data/schema.sql) into it., Project 4 6. If you are not using the XAMPP stack or if your access to MySQL is password protected, you should review and update the Yii configuration file (in NetBeans, it is ch4 | Source Files | protected | config | main.php). The admin login is admin/test.

Adding Admin Function – Library Management

Because we like to share books from our collection with our friends, we will add a lending function to our site. When a friend logs in, he/she will be able to see which books are available for borrowing, which he/she is currently borrowing, and which he/she has borrowed in the past.

Engage Thrusters

1. First, we will expand our comic book management interface with some new lending information. We will note which books we are willing to lend and while we are at it, let's make a field to track who is currently borrowing a book. Open an SQL command window for the cbdb database and run the following commands: ALTER TABLE book ADD borrower_id int(10) unsigned default null; ALTER TABLE book ADD lendable boolean default true; ALTER TABLE book ADD FOREIGN KEY ('borrower_id') REFERENCES user(id); 2. Now we must expand the book model to include the new fields (ch4 | Source Files | protected | models | Book.php). i. At the top of the model, add the new fields to the comments. This is not required, but it is good practice. * @property string $borrower_id * @property integer $lendable ii. Add a relation named borrower to connect the user who has borrowed the book, if borrower_id is set. * @property User $borrower, Level Up! Permission Levels iii. Add lendable to the numeric field check in the rules function. array('signed, bagged, lendable', 'numerical', 'integerOnly'=>true), iv. Add a check to make sure borrower_id has a maximum length of 10 in the rules() function. array('type_id, value, price, grade_id, issue_number', 'length', 'max'=>10), The previous code then becomes: array('type_id, value, price, grade_id, issue_number, borrowed_id', 'length', 'max'=>10), array('type_id, value, price, grade_id, borrower_id', 'length', 'max'=>10), v. Add lendable to the searchable list. array('id, title, type_id, publication_date, value, price, notes, signed, grade_id, bagged, issue_number, lendable', 'safe', 'on'=>'search'), vi. Add entries in the attributeLabels() function. 'borrower_id' => 'Borrower', 'lendable' => 'Lendable', vii. Add lendable to the compare criteria in the search function. $criteria->compare('lendable',$this->lendable,true); viii. Finally, add an entry named borrower for the lent field in the relations function. 'borrower' => array(self::BELONGS_TO, 'User', 'borrower_id'), 3. Now we can expand the book editing form to include the new fields (ch4 | Source Files | protected | views | book | _form.php). Add a checkbox for the lendable field.
labelEx($model,'lendable'); ?> checkbox($model, 'lendable'); ?> error($model,'lendable'); ?>
Open a book form by either editing an existing book or creating a new one. Notice that the lendable field is, by default, checked. This is because, when we created the field in MySQL, we specified that by default the value will be true. We are very generous with lending our books., Project 4 4. We will add the borrower to the form as an Ajax autocomplete field providing a list of users. To support this, we must expand the Book model (ch4 | Source Files | protected | models | Book.php) to include some transition fields. Add the following variables at the top of the Book class: public $borrower_fullname = ''; public $borrower_fname; public $borrower_lname; Also add borrower_fname and borrower_lname to the searchable list in the rules function. array('id, title, type_id, publication_date, value, price, notes, signed, grade_id, bagged, issue_number, lendable, borrower_fname, borrower_lname', 'safe', 'on'=>'search'), 5. Now, we will add an Ajax function, named aclist, to the user controller (ch4 | Source Files | protected | controllers | UserController.php) that will take the field input as a filter and return a list of users. i. Add the new action to the admin access list in the User controller. 'actions'=>array('index', 'view', 'create', 'update', 'delete', 'aclist'), ii. Add the Aclist action to the User controller. public function actionAclist($term) { $results=array(); $model = User::model(); $criteria = new CDbCriteria(); $criteria->with = array('person'); $names = preg_split('/\W/', $_GET['term'], 2); if (count($names) == 1) { $criteria->addSearchCondition( 'person.fname', $names[0], true, 'OR'); $criteria->addSearchCondition( 'person.lname', $names[0], true, 'OR'); } else { $criteria->compare('person.fname', $names[0], true); $criteria->compare('person.lname', $names[1], true); } foreach($model->findAll($criteria) as $m), Level Up! Permission Levels { $results[] = array( 'id' => $m->{'id'}, 'label' => $m->person->{'fname'} . ' ' . $m->person->{'lname'}, 'value' => $m->person->{'fname'} . ' ' . $m->person->{'lname'}, ); } echo CJSON::encode($results); } 6. Create a function in the Book controller that joins the first and last name of a borrower into a single full name field. public function set_fullname($model) { if ($model->borrower_id != null) { $model->borrower_fullname = ($model->borrower->person->fname ? $model- >borrower->person->fname . ' ' : '') . ($model->borrower->person->lname ? $model- >borrower->person->lname : '') ; } } 7. Change the update action in the Book controller to use the set_fullname function, by first loading the model, then setting the full name value, and then calling the parent update function. public function actionUpdate($id) { $model=$this->loadModel($id); $this->set_fullname($model); $this->update($model); } 8. In the Book Edit form (ch4 | Source Files | protected | views | book | _form.php), we add an auto-complete field for borrower. This field uses a Jui Zii extension, which uses jQuery to make the Ajax calls and process the responses.
labelEx($model,'borrower'); $this->widget('zii.widgets.jui.CJuiAutoComplete', array(, Project 4 'model' => $model, 'attribute' => 'borrower_fullname', 'sourceUrl' => array('user/aclist'), 'name' => 'borrower_fullname', 'options' => array ( 'minLength' => '3', 'select'=> new CJavaScriptExpression('function( event, ui ) { $("#\'.CHtml::activeId ($model,\'borrower_id\').\'") .val(ui.item.id); return true; }' ), 'htmlOptions' => array ( 'size' => 32, 'maxlength' => 32, 'value' => $model->borrower_fullname, ), )); ?>
Now, add a borrower, edit a book, and type three letters of the first or last name of a user. When you stop typing, you should see a drop-down list, containing the first name and last name entries for all of the matching users. If you are using the schema for the chapter, try rie. The results should be Best Friend and Another Friend. 9. Most of the time, a borrower will not be set when a book is created, so we must handle this case. (You can test it out by creating a book before taking this step.) Add an entry to the rules array in the Book model (ch4 | Source Files | protected | models | Book.php) to set the value of borrower_id to null, if no value is supplied. array('borrower_id', 'default', 'setOnEmpty' => true),, Level Up! Permission Levels 10. To see the new fields on the Book Index page, update the Book Index action in the Book controller (ch4 | Source Files | protected | controllers | BookController.php) to create a CDbCriteria object with the borrower.person relation and include that object in the creation of the CActiveDataProvider object. $criteria=new CDbCriteria; $criteria->with = array('borrower.person'); $dataProvider=new CActiveDataProvider('Book', array( 'criteria' => $criteria, )); 11. Add the following fields to ch4 | Source Files | protected | views | book | _view.php: getAttributeLabel('lendable')); ?>: lendable); ?>
" . CHtml::encode($data->getAttributeLabel('borrower')) . ":"; BookController::set_fullname($data); echo CHtml::encode($data->borrower_fullname); ?>
12. Then, update the Book View action to first load the model, then set the fullname, and pass it to the view as follows: public function actionView($id) { $model = $this->loadModel($id); $this->set_fullname($model); $this->render('view',array( 'model'=>$model, )); } 13. Add the fields to the attributes array in the book view (ch4 | Source Files | protected | views | book | view.php), and the individual book page will display the new fields. 'lendable', array( 'name' => 'borrower', 'value' => $model->borrower_fullname, ),, Project 4 14. To display the new fields in the admin page, edit the Book model (ch4 | Source Files | protected | models | Book.php), and add the following to the search function to search on the lendable field with the values yes or no: $criteria->compare('lendable', ($this->lendable=="yes" ? 1: ($this->lendable=="no" ? 0 : "")),true); Add these to include the related borrower and person information and to search on the borrower's first and last names. $criteria->compare('person.fname', $this- >borrower_fname, true); $criteria->compare('person.lname', $this- >borrower_lname, true); $criteria->with = array('borrower.person'); 15. Also, add a CSort object to the search function as follows: $sort = new CSort; $sort->attributes = array( 'borrower_fname' => array( 'asc' => 'person.fname', 'desc' => 'person.fname DESC', ), 'borrower_lname' => array( 'asc' => 'person.lname', 'desc' => 'person.lname DESC', ), '*', ); 16. Pass the sort variable to the CActiveDataProvider object as follows: return new CActiveDataProvider($this, array( 'criteria'=>$criteria, 'sort'=>$sort, )); 17. Finally, add the columns to the admin view (ch4 | Source Files | protected | views | book | admin.php) list. array( 'name' => 'lendable', 'header' => 'Lendable', 'value' => '(($data->lendable == 1) ? "yes" : "no")', ), array(, Level Up! Permission Levels 'name' => 'borrower_fname', 'header' => 'Borrower First Name', 'value' => '(($data->borrower != null) ? $data->borrower->person->fname . \' \' : \'\')', ), array( 'name' => 'borrower_lname', 'header' => 'Borrower Last Name', 'value' => '(($data->borrower != null) ? $data->borrower->person->lname . \' \' : \'\')', ), The final Book admin screen will look like the following screenshot:

Objective Complete - Mini Debriefing

To add the library management piece, we started by adding fields to the book table in the database. We updated the model to include the new fields. Then piece by piece, we added support for the new field in each of the book views. One area that we did not touch on was the Advanced Search form. If you would like, you can update this form to include the fields that you find useful for searching, but do not necessarily need for quick searching. To do this, edit ch4 | Source Files | protected | views | book | _search.php., Project 4

Adding User Functions – Library

Because we like to share books from our collection with our friends, we will add a lending function to our site. When a friend logs in, he/she will be able to see which books are available for borrowing, which he/she is currently borrowing, and which he/she has borrowed in the past.

Prepare for Lift Off

To demonstrate the effect of lendable/not lendable in the library, edit a few books and turn off the Lendable field.

Engage Thrusters

1. To access the new feature, we need to add a Library option to the menu, in the file ch4 | Source Files | protected | views | layouts | main.php. array('label'=>'Library', 'url'=>array('/library/index')), Log in to the site and you will see the updated menu, but clicking on this link will cause a page not found (404) error. We must create a new controller and view to support it., Level Up! Permission Levels 2. Right-click on the controllers folder (ch4 | Source Files | protected | controllers) and select New | PHP File. 3. Enter LibraryController in the File Name field and click on Finish. 4. Paste the following contents into the file: array('index'), 'users'=>array('*'), ), array('deny', // deny all users 'users'=>array('*'), ), ); } /** * Display library */ public function actionIndex() { $criteria=new CDbCriteria; $criteria->compare('lendable', 1); $dataProvider=new CActiveDataProvider ('Book', array( 'criteria' => $criteria, )); $this->render('index',array( 'dataProvider'=>$dataProvider, )); } }, Level Up! Permission Levels We have chosen to explicitly state that access rules apply to all users. You can leave the user line out, if you prefer, as it is the default value. We have added a controller with access control enabled, default layout, and one action, that is Index, which returns all the books that are lendable and not currently lent. Now if you click on Library in the menu, the error will look even worse! 5. We will fix the error by creating a view to present the results of the Library controller Index action. Begin by creating a new view folder. In NetBeans, right-click on views under ch4 | Source Files | protected and select New | Folder. 6. Enter library in the Folder Name, and click on Finish. 7. Right-click on the new library folder and select New | PHP File. Name the file index and click on Finish. 8. Replace the contents of the new index.php file with the following grid view: widget('zii.widgets.grid.CGridView', array( 'id'=>'book-grid', 'dataProvider'=>$dataProvider, 'columns'=>array( 'title', 'issue_number', array( 'name' => 'Type', 'header' => 'Type', 'value' => '$data->type->name',, Project 4 ), array( 'name' => 'Publisher', 'header' => 'Publisher', 'value' => '(($data->publisher!=null) ? $data->publisher->name : \'\')', ), array( 'name' => 'Authors', 'header' => 'Authors', 'value' => array ($dataProvider->model, 'author_list'), ), 'publication_date', array ( 'class'=>'CButtonColumn', 'template'=>'{request}', 'buttons' => array( 'request' => array( 'label' => 'Request', 'imageUrl' => Yii::app()->baseUrl . '/images/request_lozenge.png', 'url' => 'Yii::app()->createUrl ("library/request", array("id"=>$data->id))', ), ), ), ), )); ?> 9. In the library index, the Authors column takes advantage of a CGridView feature that allows you to specify an object and a function to supply the value for the column. In this case, we call the author_list function in the Book model. Open up the Book model and add that function. public function author_list($data, $row) { $list = array(); $count = 1; foreach ($data->authors as $a) { $list[] = $a->fname . ' ' . $a->lname; $count++; } return implode(",", $list); }, Level Up! Permission Levels Next, we will add a Book model function to display the book's lending status in the status column. 10. It will be nice to see the lending status of the books, whether we have them or someone else does. Let's add a status column to the library index view. 'publication_date', array( 'name' => 'Status', 'header' => 'Status', 'value' => array($dataProvider->model, 'get_status'), ), array ( 'class'=>'CButtonColumn', 11. Also, add a supporting function to the Book model. public function get_status($data, $row) { $status =""; if ($data->borrower_id != null) { $status = "Checked Out"; } if ($data->borrower_id == Yii::app()->user->getId()) { $status = "You Have It"; } if ($status == null) { $status = "Available"; } return $status; }, Project 4 12. Also in the Library index view, we added a custom link to request a book. We must add the action to the Library controller (ch4 | Source Files | protected | controllers | LibraryController.php) to process the request. But first, we will need a table to record the request. CREATE TABLE 'request' ( 'book_id' int(10) unsigned NOT NULL, 'requester_id' int(10) unsigned NOT NULL, PRIMARY KEY ('book_id','requester_id'), KEY 'requester_id' ('requester_id'), KEY 'book_id' ('book_id'), CONSTRAINT FOREIGN KEY ('book_id') REFERENCES 'book' ('id'), CONSTRAINT FOREIGN KEY ('requester_id') REFERENCES 'user' ('id') ) ENGINE=InnoDB DEFAULT 13. Use Gii to generate a model from the request table. 14. Add the new relation to the Book model (ch4 | Source Files | protected | models | Book.php). 'requesters' => array(self::MANY_MANY, 'User', 'request(requester_id, book_id)', 'index'=>'id'), 'requests' => array(self::HAS_MANY, 'Request', 'book_id', 'index' => 'requester_id'), 15. Create the request action in the Library controller (ch4 | Source Files | protected | controllers | LibraryController.php). public function actionRequest($id) { $request = new Request(); $request->book_id = $id; $request->requester_id = Yii::app()->user->getId(); $request->save(); Yii::app()->user->setFlash ('success', "Your book request has been submitted."); $this->redirect(array('index')); } 16. Add the access authorization to the Library controller access rules. 'actions'=>array('index', 'request'),, Level Up! Permission Levels 17. Add a flash display at the top of the Library index view to display success when a request is recorded. A flash message keeps the message in session through one or more of the user's requests. user->hasFlash('success')) { ?>
user->getFlash('success'); ?>
18. Add the parameter visible to the CButtonColumn in the Library index view to display the Request link if no request has been made. Once again, we will use a function defined on our model to get our result. 'request' => array( 'label' => 'Request', 'imageUrl' => Yii::app()->baseUrl . '/images/request_lozenge.png', 'url' => 'Yii::app()->createUrl("library/request", array("id"=>$data->id))', 'visible' => array($dataProvider->model, 'requested'), ), 19. Add the function requested to the Book model to support the change we just made to the view. The function will return true or false to toggle the Request link in the library grid. public function requested($row, $data) { $me = Yii::app()->user->getId(); foreach ($data->requesters as $r) { if ($r->id == $me) { return false; } } if ($data->borrower_id==$me) { return false; } return true; }, Project 4 The finished Library view looks like the following screenshot: 20. Now we will circle back to the book list view to display the requests and add the functions to process them. To display the list of requests for each book in the index view, add this section to the bottom of ch4 | Source Files | protected | views | book | _view.php. requesters) { echo "Requests\n"; echo "
\n"; foreach ($data->requesters as $r) { echo "
• " . CHtml::encode($r->person->fname . ' ' . $r->person->lname) . " " . CHtml::link("Lend", array("library/lend", "book_id" => $data->id, "user_id" => $r->id)) . "
"; } echo "
\n"; } ?>, Level Up! Permission Levels 21. To add a link next to a borrower to process a book return, change the entry for borrower in the book view to include a return link. " . CHtml::encode($data->getAttributeLabel('borrower')) . ":"; BookController::set_fullname($data); echo CHtml::encode($data->borrower_fullname) . " " . CHtml::link("Return", array("library/return", "book_id" => $data->id, "user_id" => $data->borrower_id)); ?>
22. Also, update the Library controller with this function to process a request. public function actionLend($book_id, $user_id) { $model=Book::model()->findByPk($book_id); if($model===null) throw new CHttpException(404,'The requested book does not exist.'); $request = Request::model()->find( 'book_id=:book_id AND requester_id=:user_id', array( ':book_id' => $book_id, ':user_id' => $user_id, )); if($request===null) throw new CHttpException(404,'The request does not exist.'); $request->delete(); $model->borrower_id = $user_id; $model->save(); $this->redirect(array('book/index')); } 23. The twin function to lend is return: public function actionReturn($book_id,$user_id) { $model=Book::model()->findByPk($book_id); if($model===null) throw new CHttpException(404,'The requested book does not exist.'); $model->borrower_id = null;, Project 4 $model->save(); $this->redirect(array('book/index')); } 24. Add the new action to the access rules. For the moment, it is ok to permit it for all users. We will adjust the permissions in the next task. array('allow', // allow all users to perform 'index' action 'actions'=>array('index', 'request', 'lend', return), 'users'=>array('*'), ), 25. The resulting Book index page will now include a list of requests, if any requests for the book are pending.

Objective Complete - Mini Debriefing

We have added a new action to the site that is related to an existing model, but uses its own controller. We used a function call from CGridView to display more complex column information, we used CButtonColumn to define a new button action, Request, and we added a condition to hide the button if a request has already been created. For the management piece, we updated the comic book index page to display any pending requests. We included a convenience link, Lend, that quickly updates the borrower, so that we don't have to navigate to the comic book update page, search for the new borrower, and save the changed record., Level Up! Permission Levels

Defining Roles and Access

This task is mostly about planning. When you add RBAC to your application, you will need to decide how the access to your system will be allocated. A good place to start is to look at the actions in your current system and the roles you think you will need. Yii defines RBAC in terms of roles, tasks, and operations. An operation is a single action on an object. We will set its name as the object followed by the action. For example, the name for the operation consisting of the action Create on the object Book would be bookCreate. A task is a named collection of operations. For example, you might collect all of the user management operations (userCreate, userDelete, userUpdate, and userView) into a single task named manageUser. A role is a collection of tasks and operations and other roles. Assigning one role to another creates a hierarchy and is a convenient way for the user to manage nested levels of access. For example, if you have the roles Reader, Contributor, and Administrator, it makes sense that a contributor will have all of the permissions of a reader, and an administrator will have all of the permissions of a contributor. Administrator > Contributor > Reader A user is authorized to perform any of the actions collected under a role that is assigned to him/her.

Engage Thrusters

1. For this project, we will define roles as follows, in order of decreasing levels of access: i. Authority – your role, with total access ii. Administrator – can add and edit book and user entries iii. Borrower – can view the library list and make requests iv. Viewer – can view the comic book collection v. wishlistAccess – can only view the wishlist 2. Expand this list of roles in terms of the actions they can perform: i. Authority: Create/read/update/delete role, task, operation ii. Administrator: Create/read/update/delete user, book, wish iii. Borrower: Read book, wish, library, and make library request iv. Viewer: Read book and wish v. WishlistAccess: Read wish and read/update own user entry, Project 4 3. Yii provides a function for scripting and loading all of the roles, tasks, and operations we just defined. First, we will have to set up the database to hold these new entities, and it is pretty simple. All you need are three tables to capture three things: Authorization items Authorization hierarchy Assignment 4. Go to the Servers tab, and use the Execute Command tool to create the following tables (the table definitions can be found in the directory protected/data/auth_ tables.sql): CREATE TABLE 'auth_item' ( 'name' varchar(64) NOT NULL, 'type' int NOT NULL, 'description' text, 'bizrule' text, 'data' text, PRIMARY KEY ('name') ) ENGINE=InnoDB CREATE TABLE 'auth_item_child' ( 'parent' varchar(64) NOT NULL, 'child' varchar(64) NOT NULL, PRIMARY KEY ('parent', 'child'), FOREIGN KEY ('parent') REFERENCES 'auth_item' ('name') ON DELETE CASCADE ON UPDATE CASCADE, FOREIGN KEY ('child') REFERENCES 'auth_item' ('name') ON DELETE CASCADE ON UPDATE CASCADE ) ENGINE=InnoDB CREATE TABLE 'auth_assignment' ( 'itemname' varchar(64) NOT NULL, - NOTE - userid is the format the yii libraries expect 'userid' int(10) unsigned, 'bizrule' text, 'data' text, PRIMARY KEY ('itemname', 'userid'), FOREIGN KEY ('itemname') REFERENCES 'auth_item' ('name') ON DELETE CASCADE ON UPDATE CASCADE ) ENGINE=InnoDB, Level Up! Permission Levels In the next section, we will download and install a Yii extension that will provide a nice graphical interface for RBAC management. Before we do that, we will initialize the RBAC with a script built from the hierarchy we defined in the previous steps. We have included the full script in the chapter files (ch4 | Source Files | protected | command | shell | RbacCommand.php). We will touch on some key excerpts next. For many of our controllers, we have already created more actions than the Gii-generated CRUD. For example, there are nine operations on the Wish object: $auth->createOperation('WishAdmin','admin access to wishes'); $auth->createOperation('WishIndex','index of wishes'); $auth->createOperation('WishCreate','create a wish'); $auth->createOperation('WishView','read a wish'); $auth->createOperation('WishUpdate','update a wish'); $auth->createOperation('WishDelete','delete a wish'); $auth->createOperation('WishClaim','claim a wish'); $auth->createOperation('WishRemoveAuthor','remove an author from a wish'); $auth->createOperation('WishCreateAuthor','create an author for a wish'); You may notice that the format of the operation name is . The reason for this is that the management module that we will add later relies on this naming convention. Each role in our hierarchy may be assigned the previous role and any new operations that belong to it. $role=$auth->createRole('borrower'); $role->addChild('viewer'); $role->addChild('LibraryIndex'); $role->addChild('LibraryRequest'); 5. Update the app configuration file (ch4 | protected | config | main.php) to activate the included Authorization Manager component. 'components'=>array( 'user'=>array( // enable cookie-based authentication 'allowAutoLogin'=>true, ), 'authManager' => array( 'class' => 'CDbAuthManager', 'connectionID' => 'db', 'assignmentTable' => 'auth_assignment', 'itemTable' => 'auth_item', 'itemChildTable' => 'auth_item_child',, Project 4 ), 'urlManager'=>array( 6. Run the script from the command line with the Yii shell tool to load the hierarchy into the database. cd ~/project/ch4 yiic shell >> rbac The command tool will output Rbac initialized. You can exit the tool with the command exit. 7. You can verify the initialization by going to the NetBeans server view, connecting to your database, right-clicking on any of the authorization tables, and selecting the View Data command.

Objective Complete - Mini Debriefing

When you implement a role-based access control system, you will need to give some thought to the roles that are needed in your system, the actions each role may perform, and the relationship between the roles. A review of the actions currently in your system can help you generate a list of roles. A diagram of roles and actions can help you spot gaps in your coverage., Level Up! Permission Levels

Classified Intel

At this point, you could configure your project and move from the file-based authorizations in each controller to the database authorizations that we have initialized, but maintaining and building on this information will be difficult without a more intuitive interface. The Yii team's stated intention was for developers to make suitable RBAC interfaces for their projects. You can create your own, but there are some extensions available that do a good job of meeting most RBAC management needs. So we will install one of those extensions to demonstrate a helpful graphical management interface and then complete the configuration and activate the new authorization system.

Adding the RBAC Extension

In this task, we continue to configure and activate the role-based access control system, and add a management interface to the website to make it easier to review, add to, update, and maintain the authorization information.

Prepare for Lift Off

Download and unpack the srbac and YiiSmartMenu extensions from the Yii website: f http://www.yiiframework.com/extension/srbac/ f http://www.yiiframework.com/extension/yiismartmenu/

Engage Thrusters

1. Create a directory named modules in your project's protected directory. cd ~/projects/ch4/protected mkdir modules 2. Move the srbac directory into the newly created modules directory. mv ~/Downloads/srbac\ 1.3beta/srbac/ ~/project/ch4/protected/modules/. 3. Edit the project configuration file (ch4 | protected | config | main.php) to import the srbac module. 'import'=>array( 'application.models.*', 'application.components.*', 'application.modules.srbac.controllers.SBaseController', ),, Project 4 4. In the same config file, change the AuthManager component to use the srbac module. 'authManager' => array( 'class' => 'application.modules.srbac. components.SDbAuthManager', 'connectionID' => 'db', 5. Also in the config file, add an entry for srbac to the modules array. This entry will configure the behavior of the module. 'srbac' => array( 'userclass'=>'User', //default: User 'userid'=>'id', //default: userid 'username'=>'username', //default:username 'delimeter'=>'@', //default:- 'debug'=>true, //default :false 'pageSize'=>10, // default : 15 'superUser' =>'Authority', //default: Authorizer 'css'=>'srbac.css', //default: srbac.css 'layout'=> 'application.views.layouts.main', 'notAuthorizedView'=> 'srbac.views.authitem.unauthorized', 'alwaysAllowed'=>array( 'SiteLogin', 'SiteLogout','SiteIndex', 'SiteError'), 'userActions'=>array('Show','View','List'), 'listBoxNumberOfLines' => 15, //default : 10 'imagesPath' => 'srbac.images', // default: srbac.images 'imagesPack'=>'noia', //default: noia 'iconText'=>true, // default : false 'header'=>'srbac.views.authitem.header', 'footer'=>'srbac.views.authitem.footer', 'showHeader'=>true, // default: false 'showFooter'=>true, // default: false 'alwaysAllowedPath'=>'srbac.components', ), The following points should be noted in this configuration: For the first run, we leave debugging on, which allows every user access to all screens. We leave the access to srbac open until we have used the interface to configure our admin user to have the authority permission. The alwaysAllowed line lists actions that are public on your site. Put items in this list that you want to be always accessible and do not wish to configure further., Level Up! Permission Levels 6. Create a file (ch4 | Source Files | protected | modules | srbac | components | allowed.php) that contains an empty array. Set the permissions on this file to permit writing from the web server. chown lomeara:www-data allowed.php You will be able to configure the contents of this file via the srbac web interface. 7. Remove the install folder from the project (ch4 | Source Files | protected | modules | srbac | views | authitem | install), because it provides access to administrative functions that are no longer needed. 8. Now access the srbac page http://localhost/cbdb/index.php/srbac. 9. Click on the Managing auth items button. The screen will update with a list of the Roles, Operations, and Tasks that were created by our script., Project 4 10. Click on the Create button next to the Search bar and in the form that appears, set Name to Authority, Type to Role, and Description to srbac role. 11. Click on the Create button in the form to save the new role. 12. Click on the Assign to users button., Level Up! Permission Levels 13. Select the user(s) who will have access to srbac from the left-hand column. For our examples, select the username admin. Select Authority in the right-hand column, and click on the left arrow button [ ] to move from Not Assigned Roles to Assigned Roles. As a result, the user, admin, will have the roles admin and Authority in the Assigned Roles column. 14. Now you can go back into the config file (ch4 | Source Files | protected | config | main.php) and comment out the srbac debug line, so that only the admin user can access srbac. 15. For our own convenience, we will add an srbac link to the site menu. Add the following line to ch4 | Source Files | protected | views | layouts | main.php: array('label'=>'Srbac', 'url'=>array('/srbac'), 'authItemName' => 'Authority'), For this menu item, we assign the authorized role value, Authority, to authItemName to check the access instead of depending on the URL, because srbac permits access based on this role and does not, as we have configured it, have the operations defined to match the URLs. 16. To display the applicable contents of the Comic Book menu to all users, we apply this method to the comic book item in the site menu in ch4 | Source Files | protected | views | layouts | main.php. Our lowest level access user, and all users up the hierarchy, should be able to see some items in the Comic Book menu, so we include the lowest level role as the value for authItemName. array( 'label'=>'Comic Books', 'url'=>array('/book/index'), 'items' => array( array('label'=>'Publishers', 'url'=>array('/publisher/index')),, Project 4 array('label'=>'WishList', 'url'=>array('/wish/index')), array('label'=>'Library', 'url'=>array('/library/index')), ), 'authItemName' => 'WishlistAccess', ), The Comic Book link will be visible and active, but if a user without authorization selects it, he will receive an error message. 17. The site currently uses a component, AuthMenu, that displays menu items based on authorization. We built this component in a previous chapter based on a distributed component named YiiSmartMenu to use the file-based authorization configuration. Now we will replace that component with YiiSmartMenu. Copy the file from the extension directory into your project. cp ~/Downloads/YiiSmartMenu.php ~/projects/ch4/protected/components/. 18. Change the value of the member variable partItemSeparator in the YiiSmartMenu class from "." to "" in ch4 | Source Files | protected | components | YiiSmartMenu.php. public $partItemSeparator = ""; 19. Remove the old AuthMenu file (ch4 | Source Files | protected | components | AuthMenu.php) from the project. 20. Replace the occurrences of AuthMenu in ch4 | Source Files | protected | views | layouts | column2.php and ch4 | Source Files | protected | views | layouts | main. php with YiiSmartMenu. 21. Activate the srbac by changing the parent class of ch4 | Source Files | protected | components | Controller.php to SBaseController. class Controller extends SBaseController, Level Up! Permission Levels 22. Remove or comment out the accessControl filter in every controller: BookController LibraryController PublisherController UserController WishController public function filters() { return array( //'accessControl', // perform access control for CRUD operations ); } 23. Remove or comment out the accessRules function in every controller, because it is no longer needed. 24. Try out access control by logging in as a user with fewer privileges. See the Classified Intel section for more information about test users that are already in the database.

Objective Complete - Mini Debriefing

In this section, we explained how to install, configure, and activate the srbac extension. The extension comes with its own set of instructions, but we wanted to offer a more detailed explanation to help you set it up. Also, our approach to the database tables, naming of roles, and organization of the authorization hierarchy is a little different. The configuration example we provided is slightly different from the default.

Classified Intel

You may have noticed in the initial RBAC configuration or when browsing the srbac interface that some users have been assigned to the various roles. We supplied these users in the schema for the chapter with the password for each set to test. We configured each one to a different role, so that you can test user experience for each role. The full list of users to roles is: f admin => admin f borrower => borrower f afriend => viewer f twg => wishlistAccess (twg is short for "the wish giver"), Project 4

Adding Roles to User Management

As you can see, the interface provided by the srbac extension is very powerful and convenient. It is great for adding new roles, tasks, and operations. However, when we add new users to the system, it would be convenient to assign the users, roles on the spot.

Engage Thrusters

1. First, add the relationship to the assignment object in the User model (ch4 | Source Files | protected | models | User.php). i. Add a comment at the top of the file listing the new model variable in the model relations section as follows: * The following are the available model relations: * @property Person $person * @property Assignments[] $assignments ii. Add an entry for assignments to the relations array as follows: return array( 'person' => array(self::BELONGS_TO, 'Person', 'person_id'), 'assignments' => array(self::HAS_MANY, 'Assignments', 'userid'), ); 2. Display the assignments in the User form (ch4 | Source Files | protected | views | user | _form.php):
assignments as $a) { echo "
• " . $a->itemname . "
"; } ?>
, Level Up! Permission Levels The currently assigned roles will now appear in the User edit screen as shown in the following screenshot: 3. Now we need to display the roles that have not been assigned to this user, and provide a means to add an assignment. Change the list display to use a renderPartial function as follows:
Assignments

assignments as $a) { echo $this->renderPartial('//includes/role_li', array( 'user' => $user, 'assignment' => $a, )); } ?>
4. Create a new view file for the renderPartial function call in the directory ch4 | Source Files | protected | views | includes | role_li.php with the following contents: itemname. "\">" . $assignment->itemname ., Project 4 " controller- >createUrl("/user/revokeRole", array("id" => $user->id, "role_name"=>$assignment->itemname, "ajax"=>1)) . "', '" . $assignment->itemname . "')\" " . "value=\"Revoke\" " . "/>" . ""; 5. Add a section to display a picklist of unassigned roles: Un Assigned Roles
getUnassignedRoles(), 'name', 'name'), array('size'=>5, 'class'=>'dropdown')); ?>
$user->id)); ?>" value="Add"/> 6. Create a new class variable in the User model to hold the role value as follows: public $person_fname; public $person_lname; public $role; 7. Add a function that wraps the srbac helper function getUserNotAssignedRoles to return the list of roles that have not been assigned to this user. public function getUnassignedRoles() { return(Helper::getUserNotAssignedRoles($this->id)); }, Level Up! Permission Levels 8. Now on the User edit screen, we can choose from a list of unassigned roles, to assign to the user. 9. Create the assign role action in the User controller. public function actionAssignRole($id) { // request must be made via ajax if(isset($_GET['ajax']) && isset($_GET['role'])) { $model=$this->loadModel($id); $auth = Yii::app()->authManager; $role =CHttpRequest->getParam('role'); $auth->assign($role, $id, '', ''); $role=Assignments::model()->find("itemname='" . $role . "'"); $this->renderPartial('//includes/role_li',array( 'user'=>$model, 'assignment'=>$role, ), false, true); } else throw new CHttpException(400,'Invalid request.'); } 10. Create the revoke role action in the User controller. public function actionRevokeRole($id) {, Project 4 // request must be made via ajax if(isset($_GET['ajax'])) { $auth = Yii::app()->authManager; $auth->revoke($_GET['role_name'], $id); } else throw new CHttpException(400,'Invalid request.'); } 11. Create a JavaScript file containing these functions to support the assign and revoke buttons. function revoke(url, role_name) { var role = "#role-" + role_name; $.ajax({ type: 'get', url: url, success: function(resp) { $('li').remove(role); }, error: function() { alert('error!'); } }); } $(document).ready(function() { $('.assign').click(function()$ ('.assign').click(function() { // initialize data object - it's ajax data = { "role" : $("#User_role").val(), "ajax" : "1" }; $.ajax({ type: 'get', url: $(this).attr('url'), data: data, success: function(resp) { $("ul.roles").append(resp); }, error: function() { alert('error!'); } }); }); });, Level Up! Permission Levels 12. Add clientScript calls to the beginning of update.php and create.php in the User view directory (ch4 | Source Files | protected | views | user) to include jQuery and the new custom script. Yii::app()->getClientScript()->registerCoreScript ( 'jquery.ui' ); Yii::app()->clientScript->registerScriptFile( Yii::app()->request->baseUrl . '/js/user_form_ajax.js' ); 13. Go to the srbac screen to add these new actions and assign them to the admin role, so that access to them is limited. On the srbac main screen, click on the Managing auth items button, and then click on the Create button. 14. Enter UserAssignRole as the name. Leave Type as Operation. Enter a description, if you like. Click on the Create button in the Create New Item form when you are done. 15. Click on the Create button on the left-hand side of the screen to commence adding a new operation. 16. Enter UserRevokeRole as the name. Leave Operation as the type. Enter a description, if you like. Click on Create at the bottom of the form when you are done. 17. Click on the Assign to Users button at the top of the page. 18. Go to the Tasks tab, and select manageUser under the Task column. 19. Select UserAssignRole and UserRevokeRole from the Not Assigned Operations column and click on the left arrow button [ ] to move Operations to the Assigned Operations column. 20. The actions to assign and revoke work. They update the list of assigned roles, but they do not update the select list of unassigned roles., Project 4 21. To add this feature, start by moving the select list out of the _form.php view and into its own view in ch4 | Source Files | protected | views | includes | role_select.php.
Un Assigned Roles
getUnassignedRoles(), 'name', 'name'), array('size'=>5, 'class'=>'dropdown')); ?>
$user->id)); ?>','controller->createUrl( "/user/reloadRoles", array("id"=>$user->id)); ?>')" value="Add"/>
We wrap it in a div tag with the ID role_list so we can easily replace it when we assign or revoke a role. The assignment row in ch4 | Source Files | protected | views | user | _form.php should now look like the following code snippet:
Assignments

assignments as $a) { echo $this->renderPartial('//includes/role_li', array( 'user' => $user, 'assignment' => $a, )); } ?>
renderPartial('//includes/role_select', array( 'user' => $user, )); ?>
, Level Up! Permission Levels 22. Add a new JavaScript function in ch4 | Source Files | js | user_form_ajax.js to handle the update. function update_roles(updateUrl) { // reload the role select field $.ajax({ type: 'get', url: updateUrl, data: { "ajax" : "1" }, success: function(resp) { $("#role_list").replaceWith( resp ); }, error: function() { alert('Error!'); } }); } 23. Also add a new parameter to the revoke function to pass in updateUrl and make a call to update_roles when a revoke is successful. function revoke(url, role_name, updateUrl) { success: function(resp) { $('li').remove(role); update_roles(updateUrl); }, 24. Remove the $(document).ready call and move the assign function out into a named function. Pass in the values for url and updateUrl. function assign(url, updateUrl) { $.ajax({ type: 'get', url: url, data: { "role" : $("#User_role").val(), "ajax" : "1" }, success: function(resp) { $("ul.roles").append(resp); update_roles(updateUrl); }, error: function() { alert('Error!'); } }); }, Project 4 25. Change the role list item view ch4 | Source Files | protected | views | includes | role_li.php to include an onClick call to the revoke function and pass the url variables. itemname. "\">" . $assignment->itemname . " controller- >createUrl("/user/revokeRole", array("id" => $user->id, "role_name"=>$assignment->itemname, "ajax"=>1)) . "', '" . $assignment->itemname . "', '" . Yii::app()->controller- >createUrl("/user/reloadRoles", array("id" => $user->id)) . "')\" " . "value=\"Revoke\" " . "/>" . ""; 26. Add the new reload action to the User controller. public function actionReloadRoles($id) { if(isset($_GET['ajax'])) { $model=$this->loadModel($id); $this->renderPartial ('//includes/role_select',array( 'user'=>$model, ), false, true); } else throw new CHttpException(400,'Invalid request.'); } 27. In the srbac interface, create an operation for UserReloadRoles and assign it to the manageUser task, as we just did for UserAssignRole and UserRevokeRole. Now the Assign and Revoke buttons should fully work the way we expect them to., Level Up! Permission Levels
Objective Complete - Mini Debriefing
In this task, we added a role assignment section to the User edit page. In the process, we created new controller actions to assign and revoke roles, and we used the srbac interface to limit the role assignment operations to the admin role.
Classified Intel
There is an alternate way to add operations to the system. This is particularly useful if you have added many new actions and want to create the corresponding operations all at once. 1. Go to the srbac screen. 2. Click on Managing auth items. 3. Click on the link named Autocreate Auth Items below the buttons. 4. Click on the lightbulb next to the controller that has new actions; for this task, that would have been UserController. 5. The list of actions without corresponding operations will be displayed. Click on the ones you want to add. You probably want to uncheck the box for Create Tasks, because we already have some task grouping configured. 6. You can go back to the main AuthItem management page to verify your new operations by clicking on the Managing auth items button or by clicking on the Manage AuthItem link underneath the buttons.
Fine-tuning Permissions
In relatively few steps, we have applied a finer grained access control to our site, but there may be one or two very tiny-grained areas that we have overlooked. In this task, we will clean up some access issues and, in the process, look at methods of applying even smaller areas of access control.
Engage Thrusters
1. One area not completely covered by access control is the comic book index. We display the list of requests. The admin, borrower, and viewer roles have access to this page, but only admin should be able to see the requests. To display the information only to authorized users, we need to add an authorization check. However, we do not want to check in the view itself, because views should not include business logic. Instead, we will perform the authorization check in the controller, within the Book View action, and pass the result to the view. Start by updating the index view (ch4 | Source Files | protected | views | book | index.php ) to pass a new variable named isAdmin to the ListView widget., Project 4 widget('zii.widgets.CListView', array( 'dataProvider'=>$dataProvider, 'viewData' => array('isAdmin' => $isAdmin), 'itemView'=>'_view', )); ?> 2. Update ch4 | Source Files | protected | views | book | _view.php to check this variable. requesters && $isAdmin) { echo "Requests
\n"; 3. In the Book controller (ch4 | Source Files | protected | controllers | BookController. php), perform the access control check, set the variable, and pass it to the view. $this->render('index',array( 'dataProvider'=>$dataProvider, 'isAdmin'=>Yii::app()->user->checkAccess('admin'), )); 4. We need to make the same change for the User edit screen, since we just expanded access to let users edit their own profiles. You probably don't want to allow them to choose their own level of access. i. Follow almost the same steps. Add the isAdmin field to the render call in the User Controller Update and Create actions. $this->render('update',array( 'model'=>$model, 'isAdmin'=>Yii::app()->user->checkAccess('admin'), )); ii. Pass the value to the _form render in the User Update and User Create views. renderPartial('_form', array( 'user'=>$model, 'person' => $model->person, 'isAdmin' => $isAdmin, )); ?> iii. Finally, in the User _form view, wrap the assignments row in a check for isAdmin.
Assignments
, Level Up! Permission Levels
assignments as $a) { echo $this->renderPartial('//includes/role_li', array( 'user' => $user, 'assignment' => $a, )); } ?>
renderPartial ('//includes/role_select', array( 'user' => $user, )); ?>
5. The default authorization error message provides some details about the action that was unauthorized. What if we want to present the error with less detailed information? Start by creating a folder in the views directory. cd ~/projects/ch4/protected/views mkdir srbac We named the directory srbac to associate the views in the directory with the module that will use them. 6. Create a file named access_denied.php in the new directory. 7. For our example, we will output a simple HTML error message.
Access denied.
8. Change the value of notAuthorizedView in the srbac configuration (ch4 | Source Files | protected | config | main.php) to point to the view we just created. 'notAuthorizedView'=> 'application.views.srbac.access_denied',, Project 4 9. You may have noticed that one of the tasks that we have created is named UpdateOwnUser. In the RBAC initialization script, the entry looks like this: // user task of updating own entry $bizRule='return (Yii::app()->user->id==Yii::app()- >getRequest()->getQuery('id') || Yii::app()->user->id == $params['id']);'; $task=$auth->createTask ('UpdateOwnUser','update own user entry',$bizRule); $task->addChild('UserUpdate'); 10. To give users access to edit their own user record, we have to create a point of entry, as usual by creating a menu item in ch4 | Source Files | protected | views | layouts | main.php. We will add the entry to the top-level menu, so that our users can easily find it. array( 'label'=>'Edit Profile', 'url'=>$this->createUrl('/user/update', array('id'=>Yii::app()->user->getId())), 'authItemName' => 'UpdateOwnUser', 'authParams' => array('id'=>Yii::app()->user->getId()), ), All of our roles will now have a quick link to edit the user's profile.
Objective Complete - Mini Debriefing
The srbac extension provides a default level of access control for each action. In this section, we demonstrated some ways to implement even finer-grained access control, such as displaying a portion of a view. We overrode a view in the module., Level Up! Permission Levels
Classified Intel
There is an alternate way to permit users to edit their own profiles. In this task, we demonstrated the use of a business rule, but you may prefer to keep logic out of your data layer. Another way to achieve the same effect is to perform the following steps: 1. Limit access to the UserUpdate operation to the admin role only. 2. Create a User action named Edit Profile that passes the active user ID to the Update action. public function actionEditProfile() { $this->actionUpdate(Yii::app()->user->id); } 3. In srbac, create a new operation for UserEditProfile and assign it to the base role that should be able to edit its own profile. This approach also effectively limits access to the Update action only to the user's own ID.
Making History
Along with access control comes audit logging. Once you grant more users access to your site, you have a greater need to record the actions users have taken. For example, say your comic book collection is so extensive that you hire some folks to help you input books. Maybe there are consistent errors in the data entry. If you have audit trails, you can identify who is making the errors, and give them more training to input the books with fewer errors. Another common use for audit trails is to retrieve an item that has been accidentally deleted.
Prepare for Lift Off
Download and unpack the auditTrail extension from the Yii website (http://www.yiiframework.com/extension/audittrail/).
Engage Thrusters
1. Copy the unpacked auditTrail folder into your project's modules folder. cp ~/Downloads/auditTrail ~/ch4/protected/modules/. 2. Add the module to the import array in your configuration file (ch4 | Source Files | protected | config | main.php). 'import'=>array( 'application.models.*', 'application.components.*',, Project 4 'application.modules.srbac. controllers.SBaseController', 'application.modules.auditTrail.models. AuditTrail', ), And to the modules array. 'auditTrail'=>array(), 3. Replace the entry for db in ch4 | Source Files | protected | config | console.php. 'db'=>array( 'connectionString' => 'mysql:host=localhost;dbname=cbdb', 'emulatePrepare' => true, 'username' => 'root', 'password' => '', 'charset' => 'utf8', ), 4. Edit the file yiic.php in the project root. Change the path to yiic to the absolute path. $yiic='/opt/lampp/htdocs/yii-1.1.10.r3566/framework/yiic.php'; 5. Change the model and field values in ch4 | Source Files | protected | modules | auditTrail | migrations | m110517_155003_create_tables_audit_trail.php as follows: 'model' => 'string NOT NULL', 'field' => 'string NOT NULL', Comment out the index lines for old_value and new_value. //$this->createIndex( 'idx_audit_trail_old_value', 'tbl_audit_trail', 'old_value'); //$this->createIndex( 'idx_audit_trail_new_value', 'tbl_audit_trail', 'new_value'); 6. Run the migration script supplied by the auditTrail extension. cd ~/projects/ch4/protected php ./yiic.php migrate -migrationPath=application. modules.auditTrail.migrations When the script asks you if you want to apply the changes, say Yes., Level Up! Permission Levels 7. In srbac, create an operation named auditTrail@AdminAdmin and a manageAuditTrail task. 8. In the Tasks tab under Assign to users, assign the auditTrail operation to the manageAuditTrail task. 9. Under the Roles tab, assign the manageAuditTrail task to the admin role. Access the new page at http://localhost/cbdb/index.php/auditTrail/ admin. 10. Add the Audit Trail Management page to ch4 | Source Files | protected | views | layouts | main.php so the authority user can see the link. array('label'=>'AuditTrail', 'url'=>array('/auditTrail/admin'), 'authItemName' => 'Authority'), 11. To try out the audit capture, add the following function to the User model. public function behaviors() { return array( 'LoggableBehavior'=> 'application.modules.auditTrail. behaviors.LoggableBehavior', ); } 12. Add or edit a user and then go to the Audit Trail Management page. You will see a searchable list of the changes you have made.
Objective Complete - Mini Debriefing
We installed and configured an audit trail extension to capture changes to our records.
Classified Intel
You can also add an audit trail widget to a view to show changes to an individual record. An example of this can be illustrated by adding the following snippet at the end of the User view file ch4 | Source Files | protected | views | user | view.php: widget( 'application.modules.auditTrail. widgets.portlets.ShowAuditTrail',, Project 4 array( 'model' => $model, ) ); ?>
Mission Accomplished
We have added two new features to the site: a library view for our users and library management utilities for us. To support these features and the different users of our system, we changed our access control scheme from the default access control filter to role-based access control. We installed the srbac extension to make management of the RBAC configuration easier, and we installed the AuditTrail extension to record data changes. Remember – if you put this site online, review your security and definitely disable Gii in the configuration.
You Ready to go Gung HO? A Hotshot Challenge
Here are some ideas to go gung ho with user functions: f Expand your library system by adding a Request a Book or Suggest a Book function. f Generalize the auto-complete function by creating an action extension. f Make the Book admin page editable so that you can manage your library from one screen, instead of finding a comic book and then clicking on edit to update the entry. f Create a quick entry row on the Book admin page so that you can quickly input new books with less clicking. f Add an illustrator column to the library page. f Create management and authorization for other entities such as publisher. f Add a Withdraw Request function to the library grid. f An alternate approach to permissions is an Access Control List implementation, which is appropriate when you want individual permissions versus group permissions. You could apply an ACL extension to the baseline chapter files to compare the different approaches.,
Project 5 Service Please – Integrating Service Data
This chapter is about using third-party web service APIs in your Yii application. Usually, these interfaces are implemented as RESTful web services that use JSON for data interchange. Commonly, clients that wrap these APIs are provided in a number of programming languages. Using an API in PHP is often as simple as registering with the organization as a developer and then downloading and installing the client for PHP. As Yii provides excellent support for using third-party PHP libraries, using these services with your Yii application is easy and straightforward.
Mission Briefing
We will integrate the Google OAuth2 authentication API into Yii and then set up Google authentication. Then, we will build a comic book news stream on our site that is created from the user's Google+ stream. Then, we will set up rich data interaction via Comic Vine (http://www.comicvine.com)., Service Please – Integrating Service Data
Why Is It Awesome?
An increasingly important component of modern web development is the ability to integrate third-party web services and APIs into your application. Amazon, Facebook, Flickr, Google, Groupon, NASA, Photobucket, Reddit, Salesforce.com, Twitter, the US Postal Service, the Weather Underground, and many other organizations now provide APIs to access their data. No matter what subject matter your website spans, you will probably want to use some of the functionalities and data provided and managed by these organizations. You can use some of them for authentication, offloading the work of building and securing storage of usernames and passwords. You can integrate with popular social networking websites, so members of those sites can fully participate in interactions and ratings on your site.
Your Hotshot Objectives
f Google Me – Getting Started f Google Me – Putting the Rubber to the Road f Google Me – The Yii Way f Integrating with Comic Vine – The Search, Part1fIntegrating with Comic Vine – The Search, Part2fIntegrating with Comic Vine – The Details f Putting It All Together
Mission Checklist
This project assumes that you have a web development environment prepared. If you do not have one, the tasks in Project 1, Develop a Comic Book Database, will guide you through setting one up. In order to work this project, you will need to set up the project files that have been provided with the book. Refer to the Preface of the book for instructions on downloading these files. The files for this project include a Yii project directory with a database schema. To prepare for the project, follow these steps, replacing the username james with your own username. 1. Copy the project files into your working directory. cp –r ~/Downloads/project_files/Chapter\ 5/project_files ~/projects/ch5 2. Make the directories that Yii uses web writeable. cd ~/projects/ch5/ sudo chown -R james:www-data protected/runtime assets protected/models protected/controllers protected/views, Project 5 3. Create a link in the webroot directory to the copied directory. cd /opt/lampp/htdocs sudo ln -s ~/projects/ch5 cbdb 4. Import the project into NetBeans (remember to set the project URL to http://localhost/cbdb). 5. Create a database named cbdb and load the database schema (~/projects/ch5/ protected/data/schema.sql) into it. 6. If you are not using the XAMPP stack or if your access to MySQL is password protected, you should review and update the Yii configuration file (in NetBeans it is ch5 | Source Files | protected | config | main.php). Note that the admin login is admin/test. Also, in order to work through the first three tasks, you will need a valid Google account.
Google Me – Getting Started
We need to set up the Google OAuth 2 API and integrate it with our installation of Yii, and we need to use the Google API console to set up access to the services we want to use.
Engage Thrusters
The PHP implementation of the Google OAuth 2 API requires curl for PHP. If you are using XAMPP on Linux, it should already be enabled. You can verify this by going to http://localhost/xampp/phpinfo.php and looking for the section labeled curl or the option -with-curl=/opt/lampp. 1. Find google-api-php-client and download the latest version from the downloads page. Extract it to protected/vendors in your Yii directory (if the vendors subdirectory does not exist, create it in protected first)., Service Please – Integrating Service Data 2. Go to the Google API console at https://code.google.com/apis/console/ (you will need to log in to a valid Google account) and click on Create project. 3. Put in the project name. Then, click on API Access and you should see something like this:, Project 5 4. Click on the Create an OAuth 2.0 client ID… button and fill out the form. 5. For now select Web application as the Application type, and then put in localhost for the hostname., Service Please – Integrating Service Data 6. Once you have all that set up, go to the Services tab and turn on access to Google+ API. 7. Now we will make a couple of quick changes to our project so we can test to see if everything is set up properly. 8. Create a new controller (in protected/controllers) for your Google+ feed, and name it GpfController.php. render('index', array()); } } 9. Modify views/layouts/main.php to look like this: array( 'label'=>'Comic Books', 'url'=>array('/book/index'), 'items' => array( array('label'=>'Publishers', 'url'=>array('/publisher/index')), array('label'=>'WishList', 'url'=>array('/wish/index')),, Project 5 ) ), array('label'=>'Users', 'url'=>array('/user/index')), array('label'=>'Google+ Feed', 'url'=>array('/gpf/index')), array('label'=>'Login', 'url'=>array('/site/login'), 'visible'=>Yii::app()->user->isGuest), array('label'=>'Logout ('.Yii::app()->user->name.')', 'url'=>array('/site/logout'), 'visible'=>!Yii::app()- >user->isGuest), 10. Now, add a gpf directory to views, and put a new index.php inside: breadcrumbs=array( 'gpf', ); echo "Testing, part 1.\n"; ?> 11. Set the permissions chown –R james:www-data views/gpf. When you go to http://localhost/cbdb you should be able to click on Google+ Feed, and then see the testing text. 12. We are going to incorporate the Google API PHP library and see if it is installed correctly. We will call Yii::import() to add the vendors directory to the include path. 13. Change index.php to look like the following: breadcrumbs=array( 'gpf', ); echo "Testing, part 2.\n"; ?> 14. Go to http://localhost/cbdb and click on Google+ Feed. If you don't see an error and you see the testing text, you've installed the Google Auth PHP API client correctly, and it is now working properly in your Yii environment., Service Please – Integrating Service Data
Objective Complete - Mini Debriefing
We installed the Google API client for PHP. We created a Client ID with Google to allow us to access their APIs. We turned on access to the Google+ API, so that we can see our stream. We put in a mostly empty controller class, GpfController, with a stub for the index and we added a menu item for Google+ Feed. We created a small view, and put some simple smoke tests in there to see if we can use the API client in Yii.
Google Me – Putting the Rubber to
the Road Now, we will put some simple client code using the client API in the project. Everything should be in place to fetch information from our Google+ stream, so we just have to put some code in place and provide the correct values to the API for authentication.
Engage Thrusters
For this task, we'll need SSL so that we (and Google) can access our application with HTTPS. By default, it is usually enabled for XAMPP on Linux. Verify that it is working by going to https://localhost/cbdb. If it is not enabled, go ahead and enable it (you can find a large number of "how-to" manuals online). 1. Copy the file index.php in prepared_files over the index file in protected/ views/gpf: cd ~/projects/ch5/ cp prepared_files/gplus/index.php protected/views/gpf 2. Open the Google API console, and click on API Access. Then click on Edit Settings to the right of Client ID for web applications., Project 5 3. Then set the Redirect URI to http://localhost/cbdb/index.php/gpf/index: Your final configuration will look like this:, Service Please – Integrating Service Data 4. Open protected/views/gpf/index.php. $client->setClientId('CLIENT_ID'); $client->setClientSecret('CLIENT_SECRET'); $client->setRedirectUri('http://localhost/cbdb/index.php/ gpf/index'); $client->setDeveloperKey('DEVELOPER_KEY'); 5. Replace CLIENT_ID, CLIENT_SECRET, and DEVELOPER_KEY with the values from the Google API console in the API Settings section (DEVELOPER_KEY refers to the API Key under Simple API Access). 6. Now you can go to http://localhost/cbdb and when you click on Google+ Feed, it should have you connect to Google+. 7. If you are not logged in to Google, it will ask you to authenticate:, Project 5 8. Go ahead and agree to have the mini-app we just wrote access your info. 9. Then you will see a little summary of the first few entries you would see on Google+ if you searched for #comicbooks., Service Please – Integrating Service Data
Objective Complete - Mini Debriefing
We put some simple code for fetching from our Google+ stream entirely in the view for Gpf (views/gpf/index.php). This code takes care of all the states for logging in to Google+ by saving the status of progression through the stages in the session. In order for this code to work, we had to set the redirect URI in the code and in the Google API console to https://localhost/cbdb/index.php/gpf/index (the URI of the page for viewing the Google+ feed). If these URIs do not match, you will get an error as shown in the following screenshot:
Classified Intel
The current code basically works to accomplish what we want, but we haven't implemented this using an MVC design pattern. All our logic and code is simply sitting in our view. While this was a quick and dirty way to use the API, and it hints at the power we can gain by incorporating third-party web services into our application, we haven't yet done it right. In the next task, we will do it right.
Google Me – The Yii Way
This task is about dividing the functionality implemented into the previous task into a view and a controller., Project 5
Engage Thrusters
1. Move the PHP code from the beginning of protected/views/gpf/index. php, going down to
Google+ Comic Book News Feed
(leave the breadcrumbs where they are) into the indexAction() function in protected/ controllers/GpfController.php. Move the line initializing $authUrl to the top of the function. Then make some changes in the loop to store a list of entities to pass to the view, as follows (remember to replace CLIENT_ID, CLIENT_SECRET, and DEVELOPER_KEY with the correct values): session; $client = new apiClient(); $client->setApplicationName ("Google+ Comic Book News Feed"); // Visit https://code.google.com/apis/console to //generate your oauth2_client_id, oauth2_client_secret, //and to register your oauth2_redirect_uri. client->setClientId('CLIENT_ID'); $client->setClientSecret('CLIENT_SECRET'); $client->setRedirectUri('http://localhost/cbdb/ index.php/gpf/index'); $client->setDeveloperKey('DEVELOPER_KEY'); $plus = new apiPlusService($client); if (isset($_REQUEST['logout'])) { unset($session['access_token']); }, Service Please – Integrating Service Data if (isset($_GET['code'])) { $client->authenticate(); $session['access_token'] = $client->getAccessToken(); header('Location: http://' . $_SERVER['HTTP_HOST'] . $_SERVER['PHP_SELF']); } if (isset($session['access_token'])) { $client->setAccessToken($session['access_token']); } $activityList = array(); if ($client->getAccessToken()) { $optParams = array('maxResults' => 100); $activities = $plus->activities- >search('#comicbooks'); foreach($activities['items'] as $activity) { $activityListItem = array(); $activityListItem['url'] = filter_var ($activity['url'], FILTER_VALIDATE_URL); $activityListItem['title'] = filter_var ($activity['title'], FILTER_SANITIZE_STRING, FILTER_FLAG_STRIP_HIGH); $activityListItem['content'] = $activity['object']['content']; $activityListItem['images'] = array(); if (isset($activity['object']['attachments'])) { foreach($activity['object']['attachments'] as $attachment) { if ($attachment['objectType'] === 'photo') { $activityListItem['images'][] = $attachment['image']['url']; } } } $activityList[] = $activityListItem; } $session['access_token'] = $client- >getAccessToken(); } else { $authUrl = $client->createAuthUrl(); } $this->render('index', array('activityList' => $activityList, 'authUrl' => $authUrl)); } }, Project 5 2. Change the view to reflect the changes: breadcrumbs=array( 'gpf', ); ?>
Google+ Comic Book News Feed
Your personal comic book news feed:
" . $activityListItem['title'] . '
' . $activityListItem['content'] . "
\n"); foreach($activityListItem['images'] as $imageUrl) { echo(''); echo("

\n"); } } ?>
Connect Me!"; } else { print "Logout"; } ?>
3. Now the Google+ feed in your web app should work exactly the same way it did before we started moving the code around., Service Please – Integrating Service Data

Objective Complete - Mini Debriefing

The logic responsible for communicating with the model, in this case the Google web services, now sits in the controller for our Google+ feed. The code responsible for marking up and displaying the retrieved data now sits in our view. Separating this functionality is always important when using an MVC paradigm. It makes our code more maintainable, and keeps each part of our application responsible for its own concern.

Integrating with Comic Vine – The Search, Part 1

Comic Vine's mission statement is "to be the most useful and easy to use comic book website in the world". They provide a nice API with JSON or XML formats for integration. Without special arrangement, their API is only for personal use. If you want to take your website to the masses while using their stuff, be sure to give them a call first. Comic Vine does not provide a way to look up comic books by ISSN, so we are going to implement a search by title.

Engage Thrusters

The chapter files include a simple PHP wrapper for the Comic Vine functionality that we will use. We are going to briefly discuss how this wrapper works. Here is the wrapper: setApiKey($apiKey); $this->setBaseUrl($baseUrl); } public function setAPiKey($apiKey) { $this->apiKey = $apiKey; }, Project 5 public function setBaseUrl($baseUrl) { $this->baseUrl = $baseUrl; } public static function buildQueryString($paramArray) { $paramString = http_build_query($paramArray); ; if ($paramString) { $paramString = '?' . $paramString; } return $paramString; } public static function makeRequest($url, $paramArray) { $curl = curl_init(); curl_setopt($curl, CURLOPT_URL, $url . CbdbComicVine::buildQueryString($paramArray)); curl_setopt($curl, CURLOPT_HEADER, false); curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1); $response = curl_exec($curl); $status = curl_getinfo($curl); if ($status['http_code'] == 200) { $responseObject = json_decode($response); if (is_object($responseObject) && ($responseObject->status_code == 1)) { return array('error' => 0, 'content' => $responseObject); } return array('error' => 1, 'error_type' => 'site', 'content' => $responseObject); } return array('error' => 1, 'error_type' => 'transfer', 'content' => $status); } private function setInitParams(&$params) { $params['api_key'] = $this->apiKey; $params['format'] = 'json'; return $params; }, Service Please – Integrating Service Data public function getNewParamsArray() { $params = array(); return $this->setInitParams($params); } public function baseRequest($resource, $addlParams) { $params = $this->getNewParamsArray(); $params = array_merge($params, $addlParams); return $this->makeRequest($this->baseUrl . $resource . '/', $params); } public function detailRequest($resource, $id, $addlParams) { $params = $this->getNewParamsArray(); $params = array_merge($params, $addlParams); return $this->makeRequest($this->baseUrl . $resource . '/' . $id . '/', $params); } public function volumeSearch($query, $params = array(), $offset = 0, $limit = 20) { $params['query'] = $query; $params['resources'] = 'volume'; $params['offset'] = $offset; $params['limit'] = $limit; return $this->baseRequest('search', $params); } public function issuesForVolume($volumeId, $params = array()) { $params['field_list'] = 'issues'; return $this->detailRequest('volume', $volumeId, $params); } public function volume($id, $params = array()) { return $this->baseRequest("volume/$id", $params); } public function issue($id, $params = array()) { return $this->baseRequest("issue/$id", $params); } }, Project 5 The Comic Vine API works like most web services. You create an API key and then use the key to make requests. In the previous object, it is stored in the private data member $apiKey. It is set via the constructor. By default, $baseUrl is set to http://api.comicvine.com, also via the constructor. The member function buildQueryString()takes a parameter array, populated with name-value pairs, and produces a URL query string. The member function makeRequest() accepts a URL and a parameter array, encodes the parameters as a URL query string, makes the queries using curl, and then decodes the JSON reply and returns it in native PHP data constructs. It wraps the results in an associative array containing error information in a standard format. I use getNewParamsArray() to initialize an array to set the API key and to set the format to JSON. The functions buildQueryString(), makeRequest(), and getNewParamsArray() are not intended to be used directly. They are utility functions used in combination in baseRequest() and detailRequest(), which can be used to implement most, if not all, of the functionality offered by Comic Vine. The function baseRequest() accesses resources the function and detailRequest() accesses resource details. In order to search for particular volumes and issues, we have implemented volumeSearch(), volume(), issue(), and issuesForVolume(). At this point, it is obviously trivial to implement functionality found in the API documentation for Comic Vine. Now that we have discussed the wrapper, we are going to integrate it with our website. Let's create a controller for our search. Create protected/controller/CvController. php and insert the following code snippet: redirect(array('search')); } public function actionSearch() {, Service Please – Integrating Service Data $itemList = array(); $cv = $this->newCv(); if (isset($_GET['search'])) { $offset = 0; if (isset($_GET['offset'])) { $offset = $_GET['offset']; } $result = $cv->volumeSearch($_GET['q'], array(), $offset); $this->render('search', array('model'=>$model, 'result' => $result, 'q' => $_GET['q'])); } else { $this->render('search',array('model'=>$model)); } } } Typically, we would move things like the API key into a config file. For simplicity we will leave it here. Let's look at what's going on in this controller: 1. The function actionSearch() takes whatever is passed in the 'q' parameter and conducts a volume search on it. If offset is set in the query string, it is passed along to volumeSearch() as a parameter, otherwise it defaults to 0. Let's make a simple view to test this in protected/views/cv/search.php: breadcrumbs=array( 'Comicvine', 'Search' ); if (isset($result)) { if (isset($result['content'])) { if (isset($result['content']->results)) { foreach($result['content']->results as $rec){ echo("
\n"); echo("
\n"); echo("$rec->name\n"); echo("
\n"); echo("
\n"); echo("". 'View Details' . "\n"); echo("
\n"); echo("
\n"); }, Project 5 } } } ?> 2. Let's see where that leaves us. Search for Spiderman by entering the URL http://localhost/cbdb/index.php/cv/search?search&q=Spiderman. You can click on View Details and it will open a new tab with the Comic Vine details for each result. Our search has a couple of problems. It only shows the first 20 results, and it's really not good. Let's fix the second problem so it looks a little nicer while we work on pagination. Add some styling at the very top of the file and then add a couple of lines. breadcrumbs=array( 'Comicvine', 'Search' ); if (isset($result)) { if (isset($result['content'])) { if (isset($result['content']->results)) { echo "
Results
"; foreach($result['content']->results as $rec){ echo("
\n"); echo("
\n");, Project 5 echo("$rec->name\n"); echo("
\n"); echo("
\n"); echo("". 'View Details' . "\n"); echo("
\n"); echo("
\n"); echo("
"); } } } } ?> Much better. Typically, we would put the embedded styles in a separate CSS file, but we will put it all in this file for simplicity., Service Please – Integrating Service Data Now let's fix the pagination. This will take a little more work. We will write a function to create a pagination bar, complete with links for the next and previous results. Put this at the top of the view, right below the opening PHP tag. function printPagination($result, $q) { if (isset($result['content']->offset) && isset($result['content']->limit)) { $totalResults = isset($result['content']- >number_of_total_results)?$result['content']- >number_of_total_results:0; echo("
\n"); echo("
\n"); if ($result['content']->offset != 0) { $lowerLimit = ($result['content']->offset - $result['content']->limit >= 0) ? $result['content']->offset - $result['content']->limit : 0; $upperLimit = $result['content']->offset - 1; $upperLimit = ($upperLimit > $totalResults - 1)?$totalResults - 1:$upperLimit; echo("request- >getPathInfo() . "?search=1&offset=$lowerLimit&q=$q'>Prev (" . ($lowerLimit + 1) . '-' . ($upperLimit + 1) . ")\n"); } echo("
"); echo("
\n"); $lowerLimit = $result['content']->offset; $upperLimit = $result['content']->offset + $result['content']->limit - 1; $upperLimit = ($upperLimit > $totalResults - 1)?$totalResults - 1:$upperLimit; echo(''); if ($totalResults == 0) { echo('Displaying entries 0-0 of 0.'); } else { echo('Displaying entries ' . ($lowerLimit + 1) . '- ' . ($upperLimit + 1) . " of $totalResults."); } echo('');, Project 5 echo("
"); $lowerLimit = $result['content']->offset + $result['content']->limit; if ($lowerLimit < $totalResults - 1) { $upperLimit = $result['content']->offset + 2 * $result['content']->limit - 1; $upperLimit = ($upperLimit > $totalResults - 1)?$totalResults - 1:$upperLimit; echo("
\n"); echo("request- >getPathInfo() . "?search=1&offset=$lowerLimit&q=$q'>Next(" . ($lowerLimit + 1) . '-' . ($upperLimit + 1) . ")\n"); echo("
"); } echo("
\n"); } } 3. This function simply takes the information in the result and prints a link to the next and previous results if any. Add these two lines and try it out: if (isset($result)) { if (isset($result['content'])) { printPagination($result, $q); if (isset($result['content']->results)) { echo "
Results
"; foreach($result['content']->results as $rec){ echo("
\n"); echo("
\n"); echo("$rec->name\n"); echo("
\n"); echo("
\n"); echo("". 'View Details' . "\n"); echo("
\n"); echo("
\n"); echo("
"); } } printPagination($result, $q); } }, Service Please – Integrating Service Data 4. Now add the following to the style section to make it look better: .left_pagination {float: left; width: 100px;} .center_pagination {font-weight:bold; float: left; width: 190px;} .right_pagination {float: left; width: 100px;} .pagination_row {float: left; padding: 4px;} 5. Be sure to add a div to clear the left float after the pagination row (add this line near the end of printPagination()). echo("
\n"); echo("
"); 6. You will wind up with the following result: The view displays 20 results per page, with the pagination row at the top and bottom of each page., Project 5
Objective Complete - Mini Debriefing
We covered a lot of material in this task. If the web service you are trying to use does not provide an API wrapper in a language you can use, you will have to write your own. This task has demonstrated some basic tactics to accomplish this. Then, we integrated a wrapper with a Yii controller. Pagination is often a necessary task, and we see how to deal with it in a relatively standard way when using Comic Vine. Yii has a component for handling pagination information called CPagination, but since we have already handled this on our own as an educational exercise, we won't use it for this task. In the next task, we will add a search form at the top of the screen, so you don't have to use the URL parameter to search.
Integrating with Comic Vine – The Search, Part 2
We have laid the groundwork for our Comic Vine volume search. Now we will add a search form. We will use the CActiveForm widget.
Engage Thrusters
1. Create a model for the widget to use. Create the file protected/models/ CvSearchForm.php with the following contents: 'Title Search', ); } } Our needs from the model are minimal and this should take care of it., Service Please – Integrating Service Data 2. Now add this to the controller (be sure to change the if condition to an elseif). $model = new CvSearchForm(); if (isset($_POST['CvSearchForm'])) { $itemList = array(); $model->attributes = $_POST['CvSearchForm']; if ($model->validate()) { $result = $cv->volumeSearch($model->query); $this->render('search',array( 'model' => $model, 'itemList' => $itemList, 'result' => $result, 'q' => $model->query )); } } elseif (isset($_GET['search'])) { $offset = 0; if (isset($_GET['offset'])) { $offset = $_GET['offset']; CActiveForm is used and explained extensively in Project 3, Access All Areas – Users and Logins. So if you don't know what's going on at this point you might want to refer to it. 3. In the view, add the following lines of code immediately after the breadcrumbs: $this->breadcrumbs=array( 'Comicvine', 'Search' ); $form=$this->beginWidget('CActiveForm', array( 'id'=>'search-form', 'enableClientValidation'=>true, 'clientOptions'=>array( 'validateOnSubmit'=>true, ), )); echo $form->errorSummary($model); ?>
labelEx($model,'query'); ?> textField($model,'query',array ('size'=>40, 'value' => $q)); } else { echo $form->textField($model,'query',array('size'=>40)); } ?> error($model,'query'); ?>
40)); ?>
endWidget(); if (isset($result)) { Now we have a pretty good interface for our volume search., Service Please – Integrating Service Data
Objective Complete - Mini Debriefing
In just a few lines of code, we were able to add our search box. We put the value of $q in the textbox if the q parameter is set, because this is how the link for the next and previous links are constructed, and we still want to show the query for the search in the blank.
Integrating with Comic Vine – The Details
We have a way to search for volumes, which are collections of issues. However, we don't have a way to browse and select individual issues. Let's fix that.
Engage Thrusters
We need to start by making an action for listing issues in CvController. Then, we will make a view. Sounds familiar? Let's go. 1. Change CvController to look like the following code snippet: render($view, array('error'=> $result['content']->error)); return true; } return false; }, Project 5 public function actionIndex() { $this->redirect(array('search')); } public function actionSearch() { $itemList = array(); $cv = $this->newCv(); $model = new CvSearchForm(); if (isset($_POST['CvSearchForm'])) { $itemList = array(); $model->attributes = $_POST['CvSearchForm']; if ($model->validate()) { $result = $cv->volumeSearch($model->query); $this->render('search',array( 'model' => $model, 'itemList' => $itemList, 'result' => $result, 'q' => $model->query )); } } elseif (isset($_GET['search'])) { $offset = 0; if (isset($_GET['offset'])) { $offset = $_GET['offset']; } $result = $cv->volumeSearch($_GET['q'], array(), $offset); $this->render('search', array('model'=>$model, 'result' => $result, 'q' => $_GET['q'])); } else { $this->render('search',array('model'=>$model)); } } public function actionIssues() { $cv = $this->newCv(); $title = ''; if (isset($_GET['title'])) { $title = CHtml::encode($_GET['title']);, Service Please – Integrating Service Data } if (isset($_GET['volume_id'])) { $volumeId = $_GET['volume_id']; $result = $cv->issuesForVolume($volumeId); if (!$this->errorHandler($result, 'issues')) { $issues = $result['content']->results->issues; $this->render('issues',array('result' => $issues, 'title' => $title)); } } else { $this->render('issues',array('error'=>'No volume id or issue id specified', 'result' => null)); } } } This gives us a way to fetch the issues associated with a volume ID specified in the query string as volume_id. If title is specified, we pass it through, escaping HTML special characters. We need to see what we are doing, so make a view in the file protected/views/cv/issues.php: breadcrumbs=array( 'Comicvine', ); if (isset($error)) { echo($error); } else { ?>
$title
"); } ?>
\n"); echo("
\n"); echo((int) $issue->issue_number); echo("
"); echo("
\n"); echo($issue->name?CHtml::encode ($issue->name):' '); echo("
"); echo("
\n"); echo("request->getPathInfo() . '?issue_id=' . $issue->id . "' target='_blank'>Details "); echo("
"); echo("
"); echo("
\n"); } } ?> 2. If you happen to have a valid volume ID for Comic Vine, you can now test with the URL http://localhost/cbdb/index.php/cv/issues?volume_id=2870. It does not sort by issue number, so let's fix that. 3. Add a sorting function to the controller: static function sortIssues($a, $b) { $l = $a->issue_number; $r = $b->issue_number; if ($l == $r) { return 0; } return ($l > $r) ? +1 : -1; }, Service Please – Integrating Service Data 4. Now sort the array in the action: $result = $cv->issuesForVolume($volumeId); if (!$this->errorHandler($result, 'issues')) { $issues = $result['content']->results->issues; usort($issues, array('CvController', 'sortIssues')); $this->render('issues',array('result' => $issues, 'title' => $title)); } The list is now sorted but the details link does not work. if (isset($_GET['volume_id'])) { $volumeId = $_GET['volume_id']; $result = $cv->issuesForVolume($volumeId); if (!$this->errorHandler($result, 'issues')) { $issues = $result['content']->results->issues; usort($issues, array('CvController', 'sortIssues')); $this->render('issues',array ('result' => $issues, 'title' => $title)); } } elseif (isset($_GET['issue_id'])) { $issueId = $_GET['issue_id']; $result = $cv->detailRequest('issue', $issueId, array()); if (!$this->errorHandler($result, 'issues')) { $this->redirect($result['content']->results- >site_detail_url); } } else { 5. Add the previous code snippet and the site will redirect to the Comic Vine site detail URL, after fetching the detail information for that particular issue.
Objective Complete - Mini Debriefing
Now we have a way to list issues for a particular volume. We will tie this to the volume search in the next task., Project 5
Putting It All Together
We will make a link on each volume in the volume search that shows the issues in that volume.
Engage Thrusters
At this point, all we have to do to accomplish this is to make some changes in the view. 1. Change protected/views/cv/issues.php: foreach($result['content']->results as $rec){ echo("
\n"); echo("
\n"); echo("$rec->name\n"); echo("
\n"); echo("
\n"); echo("". 'View Details' . "\n"); echo("
\n"); echo("
\n"); echo("Issues(" . $rec->count_of_issues . ')'); echo("
\n"); echo("
\n"); echo("
"); } 2. Fix the styling at the top of the file for the new field. .result_issues {float: left; width: 100px;} 3. Change the width of .result_header from 350px to 450px.
Objective Complete - Mini Debriefing
Now the volume search has a column for issues that opens a new tab with a list of issues and the volume title at the top. We have now successfully wrapped a hierarchical collection of resources in Comic Vine and incorporated it into Yii., Service Please – Integrating Service Data
Mission Accomplished
We implemented a volume search and an issue browser, both integrated with Comic Vine. Here is what the search looks like:
You Ready to go Gung HO? A Hotshot Challenge
This project has demonstrated how to incorporate a third party API into your Yii web app. Take this information to the next level by implementing either a way to tie a Comic Vine issue to an issue in our database or a way to import an issue from Comic Vine into our database to complete the integration.,
Project 6 It's All a Game
All work and no play makes James a dull boy. Game programming evokes a slightly different mindset than developing business applications. We will use these exercises to gain a new perspective. We can learn Yii and have fun too! In this chapter, we will try to prove that.
Mission Briefing
We will make two games that the user can play for fun and practice. We will leverage Yii to do this quickly with a small amount of code.
Why Is It Awesome?
Implementing a game with a development framework like Yii can be challenging and rewarding. If you implement it using the MVC model, you have to come up with a stateful model that makes sense. If you don't take the correct precautions, it is easy for the users to cheat. We can learn a lot by exploring the concepts involved.
Your Hotshot Objectives
f Updating the Database and Running Gii for Hangman f Creating a JSON Endpoint for Hangman f Developing the Controller – Creating the DB Entry f Developing the Controller – Making the Rules f Developing the View f Improving the View f Authorized Entry Only f Reusing Code – Making a New Game, It's All a Game
Mission Checklist
This project assumes that you have a web development environment prepared. If you do not have one, the tasks in Project 1, Develop a Comic Book Database, will guide you through setting one up. In order to work this project, you will need to set up the project files that have been provided with the book. Refer to the Preface of the book for instructions on downloading these files. The files for this project include a Yii project directory with a database schema. To prepare for the project, follow these steps, replacing the username james with your own username. 1. Copy the project files into your working directory. cp –r ~/Downloads/project_files/Chapter\ 6/project_files ~/projects/ch6 The source files can be downloaded from the Support page at http://www.packtpub.com/support. 2. Make the directories that Yii uses web writeable. cd ~/projects/ch6/ sudo chown -R james:www-data protected/runtime assets protected/models protected/controllers protected/views 3. Create a link in the webroot directory to the copied directory. cd /opt/lampp/htdocs sudo ln -s ~/projects/ch6 cbdb 4. Import the project into NetBeans (remember to set the project URL to http://localhost/cbdb). 5. Create a database named cbdb and load the database schema (~/projects/ch6/ protected/data/schema.sql) into it. 6. If you are not using the XAMPP stack or if your access to MySQL is password protected, you should review and update the Yii configuration file (in NetBeans: ch6 | Source Files | protected | config | main.php). 7. This project requires curl for PHP. If you are using XAMPP on Linux, it should already be enabled. You can verify this by going to http://localhost/xampp/phpinfo. php and looking for the section labeled curl or the option -with-curl=/opt/ lampp. If it is not enabled, you will need to determine how to enable it for your particular environment. Note that the admin password is test., Project 6
Updating the Database and Running Gii for Hangman
We're going to develop Hangman. The game will work as follows. A suitable title will be randomly selected from the database. It will be drawn as blanks and the user can begin guessing letters. If the letter is present, it will be filled in. Each time the user misses a letter, a new piece of the man is hung. A list of guessed letters will be kept. No letter can be guessed twice. If the user misses six letters, the entire man is hung and the game is over. We need a place to persist information about games. So in this task, we will create a database table and run Gii to create a model and a controller for the entity.
Prepare for Lift Off
Look in protected/config/main.php and make sure that the srbac debug parameter is set to true. 'srbac' => array( 'userclass'=>'User', //default: User 'userid'=>'id', //default: userid 'username'=>'username', //default:username 'delimeter'=>'@', //default:- 'debug'=>true, //default :false 'pageSize'=>10, // default : 15 'superUser' =>'Authority', //default: Authorizer 'css'=>'srbac.css', //default: srbac.css
Engage Thrusters
1. Connect to the cbdb database and run the following command to create the hangman table: CREATE TABLE `hangman` ( `id` int(10) unsigned NOT NULL AUTO_INCREMENT, `title` varchar(80) NOT NULL, `guessed` varchar(26) NOT NULL default '', `fails` tinyint(3) unsigned default 0, `token` varchar(32) NOT NULL, PRIMARY KEY (`id`), UNIQUE(`token`) ) ENGINE=InnoDB;, It's All a Game 2. Now run the model generator with Gii and point it to the hangman table, and generate a model named Hangman: 3. Click on preview and then on generate and you should see the following output: Generating code using template "/opt/lampp/htdocs/ yii-1.1.10.r3566/framework/gii/generators/model/ templates/default"... generated models/Hangman.php done! 4. Now generate a controller with the controller generator in Gii. Input hangman for the controller ID, and create play for the action IDs:, Project 6 5. Click on preview and then on generate and you should see the following output: Generating code using template "/opt/lampp/htdocs/yii- 1.1.10.r3566/framework/gii/generators/controller/ templates/default"... generated controllers/HangmanController.php generated views/hangman/create.php generated views/hangman/play.php done!
Objective Complete - Mini Debriefing
We have created a database table called Hangman with the following columns: title, guessed, fails, and token. Each row in the table will represent a single round of hangman. The table title will store the title of the book the user is trying to guess, guessed will be a string containing all the letters that have been guessed (in alphabetical order), and fails will store the number of guesses the user has got wrong. A unique lookup string (a token) that is unrelated to the ID of the record will be stored in the table token. The token should be constructed in such a way that it is very difficult (virtually impossible) to guess. We generated a model to encapsulate the hangman table as a Hangman object. We have generated a controller, named HangmanController.php, with two actions: play and create. The action create will be used to select a title and create a token, at which point it will redirect to play. play should use the token to statefully track the round of hangman. A view for each action has been added. The plan is to use the create view to display errors related to creating a new game, and to develop the view for our game in the play view. Hold these thoughts while we take a very short detour in the next task.
Creating a JSON Endpoint for Hangman
We need a way to fetch all the titles of our books, so we can randomly select one for hangman. We could fetch them all using the book model, but have chosen to instead expose this as a JSON endpoint. In this case, we will be fetching the list of books from the controller using the curl library, but we could just as easily use AJAX to fetch them from the view, or this endpoint could be the start of a web service API we could expose to third parties that would like to use our data outside our application., It's All a Game
Engage Thrusters
1. Open protected/controllers/BookController.php and add the following lines after the other actions: public function actionTitlelist() { header('Content-type: application/json'); $books = Book::model()->findAll(); $ret = array(); foreach ($books as $book) { $ret[] = $book['title']; } echo CJSON::encode($ret); Yii::app()->end(); } 2. Open a browser and navigate to http://localhost/cbdb/index.php/book/ titlelist. You should see something like the following screenshot:
Objective Complete - Mini Debriefing
This very short task has shown an ad-hoc way to produce useful JSON endpoints. Because the action in the controller calls echo, it prints it in the view, even though there is no render (and no view file).
Classified Intel
There are other ways to accomplish this. You could just put the following code in the Hangman controller we are about to write, in the create action where we will fetch the list of titles: $books = Book::model()->findAll(); $titles = array(); foreach ($books as $book) { $titles[] = $book['title']; } Then, you would not have to use curl to fetch the list., Project 6 It could be argued that serving JSON data directly through a controller does not strictly adhere to the MVC philosophy, because it is missing a view. If you still want to generate JSON, but you want to explicitly define a view, you can do that as well, by making an appropriate barebones layout and using that in the view. In that case you would call render() in the usual way, and then convert the passed data to JSON in the view.
Developing the Controller – Creating
the DB Entry We will put code in the create action for the Hangman controller to do four basic things: 1. Pick a title at random. 2. Generate a token. 3. On success, create the record, and redirect to play, passing the token as a parameter. 4. On failure, display the error in the view.
Engage Thrusters
1. Open protected/controllers/HangmanController.php and add the following function at the top of the HangmanController class: private function errorAndEnd($action, $error) { $this->render($action, array('error' => $error)); Yii::app()->end(); } When called, this will pass error to the view and cause the application to terminate. 2. Then add code to actionCreate() so it looks like the following: public function actionCreate() { $error = ''; $request = Yii::app()->request; $jsonUrl = $request->hostInfo . $request->baseUrl . '/index.php/book/titlelist'; $ch = curl_init($jsonUrl); $options = array( CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => array ('Content-type: application/json') );, It's All a Game curl_setopt_array( $ch, $options); $titles = json_decode(curl_exec($ch)); curl_close($ch); if ((!is_array($titles)) || (count($titles) == 0)) { $this->errorAndEnd('create', 'No titles found fetching from URL: ' . $jsonUrl); } for ($count = 0; $count < count($titles); $count++) { if (strlen($titles[$count]) < 8) { unset($titles[$count]); } } if (count($titles) < 1) { $this->errorAndEnd('create', 'No suitable titles found in database.'); } $titles = array_merge($titles); //Renumber the array $this->render('create', array('titles' => $titles)); } 3. Now open protected/views/hangman/create.php and make it look like the following listing: breadcrumbs=array( 'Hangman'=>array('/hangman'), 'Create', ); if (isset($error)) { echo("ERROR: $error
\n"); } else { echo(print_r($titles, 1) . "\n"); } 4. If all has gone well, you should see the dump of the $titles array when you go to http://localhost/cbdb/index.php/hangman/create:http:// localhost/cbdb/index.php/hangman/create., Project 6 Now we have verified that we are fetching the list of titles with curl. If this is not working, you may need to install curl or configure PHP. 5. Now, we will look at token creation. Add another function to the HangmanController class as follows: private function hangmanToken() { $charset = '0123456789abcdef'; $token = ''; $charArr = preg_split('//', $charset , 0, PREG_SPLIT_NO_EMPTY); for ($count = 0; $count < 32; $count++) { $token .= $charArr[mt_rand(0, count($charArr) - 1)]; } return $token; } This will create a 32-digit hexadecimal string representing a 128-bit hexadecimal number (the amount of entropy for the token is a maximum of 128 bits). We will save this string, along with our selected title, and then redirect to the play action. 6. Change the lines for actionCreate() as indicated. public function actionCreate() { $error = ''; $request = Yii::app()->request; $jsonUrl = $request->hostInfo . $request->baseUrl . '/index.php/book/titlelist'; $ch = curl_init($jsonUrl); $options = array( CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => array ('Content-type: application/json') ); curl_setopt_array( $ch, $options); $titles = json_decode(curl_exec($ch)); curl_close($ch); if ((!is_array($titles)) || (count($titles) == 0)) { $this->errorAndEnd('create', 'No titles found fetching from URL: ' . $jsonUrl); } for ($count = 0; $count < count($titles); $count++) { if (strlen($titles[$count]) < 8) { unset($titles[$count]); } }, It's All a Game if (count($titles) < 1) { $this->errorAndEnd('create', 'No suitable titles found in database.'); } $titles = array_merge($titles); //Renumber the array $hangman = new Hangman; $randCount = 0; $hangman->title = strtoupper($titles[mt_rand (0, count($titles) - 1)]); do { if ($randCount > 5) { //Even one duplicate is *highly* unlikey (1 in 2^128 if mt_rand were truly random) $this->errorAndEnd('create', 'Token generation appears to be broken.'); } $hangman->token = $this->hangmanToken(); $randCount++; } while ((Hangman::model()->find('token=:token', array(':token'=>$hangman->token))) != null); $hangman->save(); $this->redirect($request->hostInfo . $request->baseUrl . '/index.php/hangman/play?token=' . $hangman->token); } 7. Now redo the view. breadcrumbs=array( 'Hangman'=>array('/hangman'), 'Create', );?>
Hangman Game Start Error
 \n"); ?> 
, Project 6 When you go to http://localhost/cbdb/hangman/create it should redirect to something like http://localhost/cbdb/index.php/hangman/play?token=62f36f5 c03237af6f94ae952d5a43 (the token will be different, of course): You can also look in the database table and see that a record was created with the expected values., It's All a Game
Objective Complete - Mini Debriefing
At the very beginning, we added a function named errorAndEnd(). This function simply calls render() with an error string and then terminates the application. Then, in the first part of this task, we used curl to fetch JSON from the endpoint we created in the previous task and then tested it. When we set CURLOPT_RETURNTRANSFER to true, this tells curl_ exec() to return the content of the endpoint as a string. Then, we check to see if any titles were returned, and if none were, we display an error and exit with errorAndEnd(). Next, we loop through the list of returned titles and delete any shorter than eight characters (it seems like hangman is not as fun with very short titles). We check to see that we still have some viable titles, once again returning an appropriate error and ending if our check fails. We renumber the array with array_merge(), because when you use unset to remove items from an ordinal array in PHP, it doesn't renumber them. The function array_merge() can be used as a clever way to fix this. Finally, we call render(), passing the newly renumbered array $titles to the view. We create a tiny view that checks for an error. If an error is present, it is displayed, otherwise the list of titles is dumped for debugging purposes, using print_r(). This allows us to debug the first part of the task. Moving on… we needed a token, so we added the function hangmanToken(). This function is written simply in order to convey the concept of a unique token in the simplest way possible. However, it is not the best way to generate a token. You will find more information about token generation in the Classified Intel section of this task. With the statement $hangman->title = strtoupper($titles[mt_rand(0, count($titles) - 1)]); we select a random title from our list to be uppercased. We then generate a random token and check to make sure it doesn't exist by querying the database. If it does exist, which is extremely unlikely, we create another random token (if we wind up creating an existing token more than five times, something has gone very wrong and we abort). After all this, we add the token to the query string for the URL to play, and redirect there.
Classified Intel
When we discuss random numbers in computer science, we are almost always discussing pseudorandom numbers. Computers are deterministic machines by nature, and it is impossible to generate truly random numbers without expensive and highly specialized hardware. When we talk about the strength of (pseudo) random numbers, we are actually referring to the predictability of those numbers. While mt_rand() generates stronger random numbers than most implementations of rand(), it is not the best way to generate strong random numbers suitable for non-guessable tokens and cryptography. A comprehensive discussion of strong random numbers is outside the scope of this book. However, an understanding of this concept is essential to developing secure applications., Project 6 The placeholder function we wrote (hangmanToken()) is sufficient to make a fun and playable game, but the generated tokens may not withstand the scrutiny of a major government, hacker, or cryptographer who is determined to predict their values. If you wish to implement a more secure version of hangmanToken(), we encourage you to do so (see the You Ready to go Gung Ho? A Hotshot Challenge section at the end of this chapter).
Developing the Controller – Making
the Rules We will write the play action in the Hangman controller now. This is where the main part of our game will be implemented. We have to take the rules of the game, and figure out how to track them in the database table in a stateful fashion. (Obviously, we already have a good idea of how we're going to do this, since we've already created our database table and discussed what each column is for.) Then, we have to use Yii to update these states and translate them into meaningful interaction for the user.
Engage Thrusters
1. Fetch the row from the database using the token that was passed from the create action (or from the play view we will develop later). If no record is found, display an error and terminate. Add the following lines to the beginning of actionPlay() in protected/controllers/HangmanController.php: $hangman = Hangman::model()->find('token=:token', array(':token'=>$_GET['token'])); if ($hangman == null) { $this->errorAndEnd('play', 'Invalid token.'); } 2. Change $this->render('play'); to $this->render('play', array('token' => $hangman->token)); at the bottom of the function, so we can see what's going on. Now change the view (protected/views/hangman/ play.php) to reflect this and let's test these small changes: breadcrumbs=array( 'Hangman'=>array('/hangman'), 'Play', ); if (isset($error)) { echo("
CBDB Hangman Error

\n"); echo("
Error: $error

\n"); }, It's All a Game else { echo("
CBDB Hangman

\n"); echo("
Token: $token

\n"); } Now you should see something like the following screenshot: 3. Put in an invalid token value and you should see the following screenshot:, Project 6 4. Add some additional code to actionPlay() and change the render to include the new information. public function actionPlay() { $hangman = Hangman::model()->find('token=:token', array(':token'=>$_GET['token'])); if ($hangman == null) { $this->errorAndEnd('play', 'Invalid token.'); } $title = strtoupper($hangman->title); $guessed = array(); foreach (preg_split('//', $hangman->guessed , 0, PREG_SPLIT_NO_EMPTY) as $letter) { $guessed[$letter] = 1; } $maskedTitle = ''; foreach (preg_split('//', $title, 0, PREG_SPLIT_NO_EMPTY) as $letter) { if (!isset($guessed[$letter]) && ctype_alpha($letter)) { $maskedTitle .= '_ '; } else { $maskedTitle .= $letter . ' '; } } $maskedTitle = preg_replace('/ /', ' ', $maskedTitle); $this->render('play', array('maskedTitle' => $maskedTitle, 'guessed' => $hangman->guessed)); } 5. Once again, change the view so we can see what's going on: breadcrumbs=array( 'Hangman'=>array('/hangman'), 'Play', ); if (isset($error)) { echo("
CBDB Hangman Error

\n"); echo("
Error: $error

\n"); } else { echo("
CBDB Hangman

\n");, It's All a Game echo("
Title: $maskedTitle

\n"); echo("
Guessed: $guessed

\n"); } ?> 6. Now creating a new game by going to http://localhost/cbdb/index.php/ hangman/create or loading an existing game from play should show something like the following screenshot: 7. Now we need to make a way for the controller to check for wins, losses, and to process guesses. We will add a function and change actionPlay() to accomplish this: private function assessWin($guesses, $title) { $guessArr = array(); foreach (preg_split('//', strtoupper($guesses), 0, PREG_SPLIT_NO_EMPTY) as $letter) { $guessArr[$letter] = true; } foreach (preg_split('//', strtoupper($title), 0, PREG_SPLIT_NO_EMPTY) as $letter) { if (!isset($guessArr[$letter]) && ctype_alpha($letter)) { return false; } }, Project 6 return true; } public function actionPlay() { $message = ''; if (!isset($_GET['token'])) { $this->errorAndEnd('play', 'No token set.'); } $token = $_GET['token']; $hangman = Hangman::model()->find('token=:token', array(':token'=>$token)); if ($hangman == null) { $this->errorAndEnd('play', 'Invalid token.'); } $title = strtoupper($hangman->title); $win = false; $lose = false; if ($hangman->fails > 5) { $lose = true; } else { $win = $this->assessWin($hangman->guessed, $hangman- >title); if (!$win && isset($_GET['guess'])) { $guess = strtoupper($_GET['guess']); if (strlen($guess) == 1 && ctype_alpha($guess) && !strstr($hangman->guessed, $guess)) { if (!strstr($title, $guess)) { $hangman->fails++; if ($hangman->fails > 5) { $lose = true; } } $hangman->guessed .= $guess; $guessed = preg_split('//', $hangman->guessed, 0, PREG_SPLIT_NO_EMPTY); sort($guessed); $hangman->guessed = implode($guessed); $hangman->save(); $win = $this->assessWin($hangman->guessed, $hangman- >title); } else {, It's All a Game $message .= 'Invalid guess. Please enter a single letter that hasn't already been guessed.'; } } } $guessed = array(); foreach (preg_split('//', $hangman->guessed, 0, PREG_SPLIT_NO_EMPTY) as $letter) { $guessed[$letter] = 1; } $maskedTitle = ''; foreach (preg_split('//', $title, 0, PREG_SPLIT_NO_EMPTY) as $letter) { if (!isset($guessed[$letter]) && ctype_alpha($letter)) { $maskedTitle .= '_ '; } else { $maskedTitle .= $letter . ' '; } } $maskedTitle = preg_replace('/ /', ' ', $maskedTitle); $this->render('play', array('maskedTitle' => $maskedTitle, 'guessed' => $hangman->guessed, 'fails' => $hangman->fails, 'win' => $win, 'lose' => $lose, 'title' => $title, 'token' => $hangman->token, 'message' => $message)); } 8. Make one final change to the view, so we can see what we have done. breadcrumbs=array( 'Hangman'=>array('/hangman'), 'Play', ); if (isset($error)) { echo("
CBDB Hangman Error

\n"); echo("
Error: $error

\n"); } else { echo("
Welcome to CBDB Hangman

\n");, Project 6 echo("Title: $maskedTitle

\n"); echo("Guessed: $guessed
\n"); echo("Fails: $fails
\n"); if ($win) { echo("


You Win!!!

\n"); } elseif ($lose) { echo("


You Lose :(

\n"); echo("
The answer was $title.

\n"); } } Now, you can actually play Hangman by appending guesses to the parameter string like this: http://localhost/cbdb/index.php/hangman/play?token=85eab6e8ba42169fbf 7c8c72355&guess=r You will see something like the following screenshot as you guess letters:, It's All a Game If you repeat a guess, it has absolutely no effect. If you pass more than one letter, or a non-alphabetical character, the guess is not processed. Regardless of whether you enter a lowercase letter, or uppercase letter, the letter is uppercased and processed. If you guess a letter that is not in the title, $fails increments (which is displayed in the view). you can see that this one is GREEN LANTERN, so you can finish the title and make sure that a win is detected: Let's start a new game to test losing. Once you get six failures, a loss is detected. Six failures to a loss is based on these body parts for the hangman: head, torso, left arm, right arm, left leg, and right leg. When a loss is detected, this is what happens:, Project 6 If a particular game is played to a loss or a win, you can see the final state of the game by going to the play URL with the token, but you cannot change it.
Objective Complete - Mini Debriefing
We covered a lot of ground in this task. We are going to go over the final version of the controller and explain each piece of what we have accomplished. The function assessWin() determines if a game has been won by checking to see if all the letters have been guessed, and returns true for a win or false otherwise. We added the following code snippet to handle the case where the token is not passed at all. if (!isset($_GET['token'])) { $this->errorAndEnd('play', 'No token set.'); } Next, logic was added to check for a loss, check for a win, process a guess, and then check for a win again., It's All a Game When we process the guess, we validate it to make sure it is correct and hasn't already been guessed. if (!$win && isset($_GET['guess'])) { $guess = strtoupper($_GET['guess']); if (strlen($guess) == 1 && ctype_alpha($guess) && !strstr($hangman->guessed, $guess)) { if (!strstr($title, $guess)) { $hangman->fails++; if ($hangman->fails > 5) { $lose = true; } } $hangman->guessed .= $guess; $guessed = preg_split('//', $hangman->guessed, 0, PREG_SPLIT_NO_EMPTY); sort($guessed); $hangman->guessed = implode($guessed); $hangman->save(); $win = $this->assessWin($hangman->guessed, $hangman->title); } else { $message .= 'Invalid guess. Please enter a single letter that hasn't already been guessed.'; } } If the guess is not in the title, we increment $hangman->fails and check for a loss. We append the guess to $guessed, sort the letters in $guessed alphabetically, and reassign the string to $hangman->guessed. Then we call $hangman->save() to save $hangman- >guessed (and $hangman->fails if needed). Then, we check for a win one final time. The final call to $this->render() is modified to return the values the view will need. The view checks for an error, and if there is no error, displays relevant info about the game.
Developing the View
We've coded all the rules in the play and create actions in our controller, but our view doesn't really look like hangman. Also, guessing the letter by modifying the query string isn't really the most intuitive of user interfaces. However, at this point, we have tested all the functionality of the controller, and it seems solid, so we have a good foundation to start work on the final layer. Let's get to work on the view!, Project 6
Prepare for Lift Off
We have produced some artwork to help us with this step. The images can be found in the images/hangman directory of our webroot. If you want, you can take a look at them before we get started, so you can see how this will all fit together.
Engage Thrusters
All the work done in this task will be in the view for play. 1. Start with protected/views/play.php as follows: breadcrumbs=array( 'Hangman'=>array('/hangman'), 'Play', ); if (isset($error)) { echo("
CBDB Hangman Error

\n"); echo("
Error: $error

\n"); } else { echo("
Welcome to CBDB Hangman

\n"); echo("
\n"); echo("Title: $maskedTitle

\n"); echo("Fails: $fails
\n"); echo("Guessed: $guessed
\n"); if ($win) { echo("


You Win!!!

\n"); } elseif ($lose) { echo("


You Lose :(

\n"); echo("
The answer was $title.

\n"); } echo("
\n"); } ?>, It's All a Game 2. Now let's incorporate those images I was showing you, to get started. Below the title Welcome to CBDB Hangman, place the following line: echo("
Welcome to CBDB Hangman

\n"); echo("
\n"); echo("
\n"); echo("Title: $maskedTitle

\n"); Let's look at what that one line got us:, Project 6 3. It would be nicer if we could move the image to the right and display the interactive text to the left. breadcrumbs=array( 'Hangman'=>array('/hangman'), 'Play', ); if (isset($error)) { echo("
CBDB Hangman Error

\n"); echo("
Error: $error

\n"); } else { ?>
Welcome to CBDB Hangman


\n"); echo("
\n"); echo("
\n"); echo("Title: $maskedTitle

\n"); echo("Fails: $fails
\n"); echo("Guessed: $guessed
\n"); if ($win) { echo("


You Win!!!

\n"); } elseif ($lose) { echo("


You Lose :(

\n"); echo("
The answer was $title.

\n"); } echo("
\n"); } ?>, It's All a Game 4. Let's make it easy to start a new game, and make it easy to go to the index page. Add the following two lines after the image tag and then throw in some
tags: echo("
\n"); echo("
\n"); echo("New Game
"); echo("Back to CBDB
"); echo("
\n"); echo("
\n"); echo("Title: $maskedTitle

\n"); echo("Fails: $fails
\n"); echo("Guessed: $guessed
\n"); echo("
\n"); Now it should look like the following screenshot: This gives us almost everything we need, with just a few lines of code. The only thing we still need is a way to make guesses, other than manually modifying parameters in the query string. It should be fairly straightforward to make a tiny form that simply submits the guess., Project 6 5. Make the final version of your view look like the following code snippet (We moved some things around to make it prettier, and added the aforementioned form), and we'll discuss what we've done: breadcrumbs=array( 'Hangman'=>array('/hangman'), 'Play', ); if (isset($error)) { echo("
CBDB Hangman Error

\n"); echo("
Error: $error

\n"); } else { ?>
Welcome to CBDB Hangman


\n"); echo("
\n"); echo("
New Game
"); echo("Back to CBDB
"); echo("
\n"); echo("

\n"); echo("Title: $maskedTitle

\n"); echo("Fails: $fails
\n"); echo("Guessed: $guessed
\n"); echo("

\n"); if ($win) { echo("



You Win!!!


\n");, It's All a Game } elseif ($lose) { echo("



You Lose :(


\n"); echo("

The answer was $title.


\n"); } else { ?>
\n"); ?> Guess:
\n"); echo("$message
\n"); echo("