Documentation/general/models.html

   1 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   2 <head>
   3         <title>CarbonPHP Documentation</title>
   4         <style type="text/css">
   5                 * {
   6                         margin: 0;
   7                         padding: 0;
   8                 }
   9
  10                 html {
  11                         font-family: "Lucida Sans Unicode", "Lucida Grande";
  12                         font-size: 12px;
  13                 }
  14
  15                 body {
  16                         background: #fff;
  17                         color: #666;
  18                 }
  19
  20                 h1 {
  21                         font-size: 15px;
  22                         font-weight: bold;
  23                         margin-bottom: 5px;
  24                 }
  25
  26                 ol, ul {
  27                         margin: 10px 0 10px 0;
  28                         list-style-position: inside;
  29                 }
  30
  31                 p {
  32                         margin: 5px 0 5px 0;
  33                 }
  34
  35                 .content {
  36                         border: 1px dotted #444;
  37                         margin: 10px;
  38                         padding: 10px;
  39                         text-align: justify;
  40                         width: 700px;
  41                 }
  42
  43                 .example {
  44                         border: 1px solid #ccc;
  45                         background: #eee;
  46                         margin: 10px;
  47                         padding: 10px;
  48                 }
  49         </style>
  50 </head>
  51
  52 <body>
  53         <div class="content">
  54                 <h1>Models</h1>
  55
  56                 <p>You are not required to use models in your web application.  They can be used for those people who wish
  57                 to use a more traditional model-view-controller approach.</p>
  58         </div>
  59
  60         <div class="content">
  61                 <h1>What is a Model?</h1>
  62
  63                 <p>Models are classes that are designed to handle information in your databases.  An example is if you
  64                 create a blog application using CarbonPHP.  You may have a model class that has methods to insert, update,
  65                 and retrieve blog data.</p>
  66
  67                 <p>An example of this model may look like the following.</p>
  68
  69                 <div class="example">
  70                         &lt;?php<br />
  71                         <br />
  72                         class Blogmodel extends Model<br />
  73                         &#123;<br />
  74                         &nbsp;&nbsp;&nbsp;&nbsp;public $title = '';<br />
  75                         &nbsp;&nbsp;&nbsp;&nbsp;public $content = '';<br />
  76                         &nbsp;&nbsp;&nbsp;&nbsp;public $data = '';<br />
  77                         <br />
  78                         &nbsp;&nbsp;&nbsp;&nbsp;public function __construct()<br />
  79                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
  80                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;parent::__construct();<br />
  81                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
  82                         <br />
  83                         &nbsp;&nbsp;&nbsp;&nbsp;public function get_last_ten_entries()<br />
  84                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
  85                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$query = $this->db->get('entries', 10);<br />
  86                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return $query->result();<br />
  87                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
  88                         <br />
  89                         &nbsp;&nbsp;&nbsp;&nbsp;public function insert()<br />
  90                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
  91                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->title = $_POST['title'];<br />
  92                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->content = $_POST['content'];<br />
  93                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->date = time();<br />
  94                         <br />
  95                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->db->insert('entries', $this);<br />
  96                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
  97                         <br />
  98                         &nbsp;&nbsp;&nbsp;&nbsp;public function update()<br />
  99                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
 100                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->title = $_POST['title'];<br />
 101                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->content = $_POST['content'];<br />
 102                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->date = time();<br />
 103                         <br />
 104                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->db->update('entries', $this, array('id', $_POST['id']));<br />
 105                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
 106                         &#125;<br />
 107                         <br />
 108                         ?&gt;
 109                 </div>
 110
 111                 <p><i>Note</i>: the above example is using methods from the <b>Active Record</b> data class.</p>
 112         </div>
 113
 114         <div class="content">
 115                 <h1>The Anatomy of a Model</h1>
 116
 117                 <p>Models are stored the in <b>application/models/</b> directory.  They can be stored in subdirectories for
 118                 people who wish to use that type of organisation.</p>
 119
 120                 <div class="example">
 121                         &lt;?php<br />
 122                         <br />
 123                         class Model_name extends Model<br />
 124                         &#123;<br />
 125                         &nbsp;&nbsp;&nbsp;&nbsp;public function __construct()<br />
 126                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
 127                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;parent::__construct();<br />
 128                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
 129                         &#125;<br />
 130                         <br />
 131                         ?&gt;
 132                 </div>
 133
 134                 <p><b>Model_name</b> is the name of your class.  Class names must be capitalised.  You must also make sure
 135                 that the model class extends the base <b>Model</b> class.  The file name will be a lower case version of
 136                 the class name.</p>
 137
 138                 <div class="example">
 139                         &lt;?php<br />
 140                         <br />
 141                         class User_model extends Model<br />
 142                         &#123;<br />
 143                         &nbsp;&nbsp;&nbsp;&nbsp;public function __construct()<br />
 144                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
 145                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;parent::__construct();<br />
 146                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
 147                         &#125;<br />
 148                         <br />
 149                         ?&gt;
 150                 </div>
 151
 152                 <p>The model file name will be the following.</p>
 153
 154                 <div class="example">
 155                         application/models/<b>user_model.php</b>
 156                 </div>
 157         </div>
 158
 159         <div class="content">
 160                 <h1>Loading a Model</h1>
 161
 162                 <p>Usually your models will be loaded and used from within your controllers methods.</p>
 163
 164                 <div class="example">
 165                         $this->load->model('<b>Model_name</b>');
 166                 </div>
 167
 168                 <p>If you have organised your models in subdirectories you will need to include the directory in the
 169                 method call.</p>
 170
 171                 <div class="example">
 172                         $this->load->model('<b>Directory_name</b>/<b>Model_name</b>');
 173                 </div>
 174
 175                 <p>Once your model has been loaded you will access the models methods using an object with the same
 176                 name as the model class you loaded.</p>
 177
 178                 <div class="example">
 179                         $this->load->mode('<b>Model_name</b>');<br />
 180                         $this-><b>Model_name</b>->method();
 181                 </div>
 182
 183                 <p>You can specify a different name for the model object in the second parameter of the loading method.</p>
 184
 185                 <div class="example">
 186                         $this->load->model('<b>Model_name</b>', '<b>foo</b>');<br />
 187                         $this-><b>foo</b>->method();
 188                 </div>
 189
 190                 <p>An example of a controller that loads and uses a model, then loads a view is shown below.</p>
 191
 192                 <div class="example">
 193                         &lt;?php<br />
 194                         <br />
 195                         class Blog extends Controller<br />
 196                         &#123;<br />
 197                         &nbsp;&nbsp;&nbsp;&nbsp;public function recent()<br />
 198                         &nbsp;&nbsp;&nbsp;&nbsp;&#123;<br />
 199                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->load->model('Blog');<br />
 200                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$data['query'] = $this->blog->get_last_ten_entries();<br />
 201                         &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$this->load->view('blog_view', $data);<br />
 202                         &nbsp;&nbsp;&nbsp;&nbsp;&#125;<br />
 203                         &#125;<br />
 204                         <br />
 205                         ?&gt;
 206                 </div>
 207         </div>
 208
 209         <div class="content">
 210                 <h1>Using a Database in Models</h1>
 211
 212                 <p>Unless you autoload the database library (this is explained later) you model will not automaticall connect
 213                 to your database.  There are three methods you can use for connecting to the database in your models.</p>
 214
 215                 <ul>
 216                         <li>Connect using the standard database methods, either in your controller or model class.</li>
 217                         <li>You can tell the model loading method to connect to the database by passing <b>true</b> via
 218                         the third parameter, and settings for your database defined in the configuration file
 219                         <b>config/database.php</b>.</li>
 220
 221                         <div class="example">
 222                                 $this->load->model('<b>Model_name</b>', '', true);
 223                         </div>
 224
 225                         <li>You can manually the pass the database connection settings via the third parameter.</li>
 226
 227                         <div class="example">
 228                                 $config['hostname'] = 'localhost';<br />
 229                                 $config['username'] = 'dbuser';<br />
 230                                 $config['passwprd'] = 'dbpassword';<br />
 231                                 $config['database'] = 'databasename';<br />
 232                                 $config['dbdriver'] = 'mysql';<br />
 233                                 $config['dbprefix'] = '';<br />
 234                                 $config['pconnect'] = false;<br />
 235                                 $config['db_debug'] = true;<br />
 236                                 $config['active_r'] = true;<br />
 237                                 <br />
 238                                 $this->load->model('<b>Model_name</b>', '', $config);
 239                         </div>
 240                 </ul>
 241         </div>
 242 </body>
 243
 244 </html>