Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 179 lines (106 sloc) 8.192 kb
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
1 # Migrating from 3.0.x
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
2
30a000c Matt Button Adding more complete upgrade docs for the config system rewrite
BRMatt authored
3 ## Config
4
f3979f8 Andrew Coulton Clarify that configuration is now merged across all sources in the upgra...
acoulton authored
5 The configuration system has been rewritten to make it more flexible. The most significant change is that config groups are now merged across all readers, similar to how files cascade within the cascading filesystem. Therefore you can now override a single config value (perhaps a database connection string, or a 'send-from' email address) and store it in a separate config source (environment config file / database / custom) while inheriting the remaining settings from that group from your application's configuration files.
6
7 In other respects, the majority of the public API should still operate in the same way, however the one major change is the transition from using `Kohana::config()` to `Kohana::$config->load()`, where `Kohana::$config` is an instance of `Config`.
30a000c Matt Button Adding more complete upgrade docs for the config system rewrite
BRMatt authored
8
9 `Config::load()` works almost identically to `Kohana::config()`, e.g.:
10
11 Kohana::$config->load('dot.notation')
12 Kohana::$config->load('dot')->notation
13
14 A simple find/replace for `Kohana::config`/`Kohana::$config->load` within your project should fix this.
15
16 The terminology for config sources has also changed. Pre 3.2 config was loaded from "Config Readers" which both
17 read and wrote config. In 3.2 there are **Config Readers** and **Config Writers**, both of which are a type of
18 **Config Source**.
19
20 A **Config Reader** is implemented by implementing the `Kohana_Config_Reader` interface; similarly a **Config Writer**
21 is implemented by implementing the `Kohana_Config_Writer` interface.
22
23 e.g. for Database:
24
25 class Kohana_Config_Database_Reader implements Kohana_Config_Reader
26 class Kohana_Config_Database_Writer extends Kohana_Config_Database_Reader implements Kohana_Config_Writer
27
28 Although not enforced, the convention is that writers extend config readers.
29
30 To help maintain backwards compatability when loading config sources empty classes are provided for the db/file sources
31 which extends the source's reader/writer.
32
33 e.g.
34
35 class Kohana_Config_File extends Kohana_Config_File_Reader
36 class Kohana_Config_Database extends Kohana_Config_Database_Writer
37
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
38 ## Request/Response
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
39
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
40 The request class has been split into a request and response class. To set the response body, you used to do:
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
41
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
42 $this->request->response = 'foo';
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
43
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
44 This has changed to:
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
45
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
46 $this->response->body('foo');
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
47
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
48 Some properties that existed in the request class have been converted into methods:
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
49
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
50 - Request::$controller -> Request::controller()
51 - Request::$action -> Request::action()
52 - Request::$directory -> Request::directory()
53 - Request::$uri -> Request::uri()
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
54
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
55 Request::instance() has been replaced by Request::current() and Request::initial(). Normally you'll want to use Request::current(), but if you are sure you want the *original* request (when running hmvc requests), use Request::initial().
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
56
068459a Sam de Freyssinet Updated upgrading documentation to reflect some of the changes in 3.2 wi...
samsoir authored
57 ### External requests in Kohana 3.2
58
59 In Kohana 3.2, `Request_Client_External` now has three separate drivers to handle external requests;
60
61 - `Request_Client_Curl` is the default driver, using the PHP Curl extension
62 - `Request_Client_HTTP` uses the PECL HTTP extension
63 - `Request_Client_Stream` uses streams native to PHP and requires no extensions. However this method is slower than the alternatives.
64
65 Unless otherwise specified, `Request_Client_Curl` will be used for all external requests. This can be changed for all external requests, or for individual requests.
66
67 To set an external driver across all requests, add the following to the `application/bootstrap.php` file;
68
69 // Set all external requests to use PECL HTTP
70 Request_Client_External::$client = 'Request_Client_HTTP';
71
72 Alternatively it is possible to set a specific client to an individual Request.
73
74 // Set the Stream client to an individual request and
75 // Execute
76 $response = Request::factory('http://kohanaframework.org')
77 ->client(new Request_Client_Stream)
78 ->execute();
79
80 ### HTTP cache control in 3.2
81
82 Kohana 3.1 introduced HTTP cache control, providing RFC 2616 fully complient transparent caching of responses. Kohana 3.2 builds on this moving all caching logic out of `Request_Client` into `HTTP_Cache`.
83
84 [!!] HTTP Cache requires the Cache module to be enabled in all versions of Kohana!
85
86 In Kohana 3.1, HTTP caching is enabled doing the following;
87
88 // Apply cache to a request
89 $request = Request::factory('foo/bar', Cache::instance('memcache'));
90
91 // In controller, ensure response sets cache control,
92 // this will cache the response for one hour
93 $this->response->headers('cache-control',
94 'public, max-age=3600');
95
96 In Kohana 3.2, HTTP caching is enabled slightly differently;
97
98 // Apply cache to request
99 $request = Request::factory('foo/bar',
100 HTTP_Cache::factory(array(), 'memcache'));
101
102 // In controller, ensure response sets cache control,
103 // this will cache the response for one hour
104 $this->response->headers('cache-control',
105 'public, max-age=3600');
106
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
107 ## Validation
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
108
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
109 The validation class has been improved to include "context" support. Because of this, the api has changed. Also, The class has been split: core validation logic is now separate from built-in validation rules. The new core class is called `Validation` and the rules are located in the `Valid` class.
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
110
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
111 ### Context
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
112
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
113 The validation class now contains "context" support. This allowed us to merge the rule() and callback() methods, and there is now simply a rule() method that handles both cases.
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
114
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
115 Old usage:
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
116
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
117 rule('password', 'matches', array('repeat_password'))
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
118
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
119 New usage:
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
120
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
121 rule('password', 'matches', array(':validation', 'password', 'repeat_password'))
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
122
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
123 The third parameter now contains all parameters that get passed to the rule. If you look at Valid::matches(), you'll see:
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
124
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
125 public static function matches($array, $field, $match)
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
126
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
127 :validation is the first parameter, 'password' is the second (the field we want to check) and 'repeat_password' is the third (what we want to match)
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
128
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
129 :validation is a special "context" variable that tells the Validation class to replace with the actual validation class. You can see in this way, the matches rule is no different than how callbacks used to work, yet are more powerful. There are other context variables:
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
130
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
131 - :validation - The validation object
132 - :field - The field being compared (rule('username', 'min_length', array(':field', 4)))
133 - :value - The value of the field
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
134
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
135 You can use any php function as a rule if it returns a boolean value.
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
136
129d45a Jeremy Bush Adding note in upgrade guide about validation filters being removed
zombor authored
137 ### Filters
138
139 Filters have been removed from the validation class. There is no specific replacement. If you were using it with ORM, there is a new mechanism for filtering in that module.
140
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
141 ## Cookie salts
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
142
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
143 The cookie class now throws an exception if there isn't a salt set, and no salt is the now the default. You'll need to make sure you set the salt in your bootstrap:
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
144
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
145 Cookie::$salt = 'foobar';
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
146
3883cf4 Jeremy Bush Docs: Add 404 handling note to migration guide, fix various typos
zombor authored
147 Or define an extended cookie class in your application:
148
149 class Cookie extends Kohana_Cookie
150 {
151 public static $salt = 'foobar';
152 }
153
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
154 ## Controller constructor
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
155
a39cd8a Jeremy Bush Updates to userguide: upgrading from 3.0, exception handling, etc
zombor authored
156 If for some reason you are overloading your controller's constructor, it has changed to:
928c6ff Isaiah DeRose-Wilson Merging in 3.0.x branch
isaiahdw authored
157
5e3a93d Jeremy Bush Docs: adding upgrade note about index.php/bootstrap.php
zombor authored
158 public function __construct(Request $request, Response $response)
159
160 ## index.php / bootstrap.php changes
161
3883cf4 Jeremy Bush Docs: Add 404 handling note to migration guide, fix various typos
zombor authored
162 The main change here is that the request execution has been removed from bootstrap.php and moved to index.php. This allows you to use one bootstrap when doing testing. The reason for this change is that the bootstrap should only setup the environment. It shouldn't run it.
163
164 ## 404 Handling
165
0a4d609 Woody Gilk Changed all internal references to Http to HTTP, because HTTP is an acro...
shadowhand authored
166 Kohana now has built in exception support for 404 and other http status codes. If you were using ReflectionException to detect 404s, you should be using HTTP_Exception_404 instead. For details on how to handle 404s, see [error handling](errors).
4ea94f4 Jeremy Bush Docs: Adding note about changed form::open to upgrade guide
zombor authored
167
168 ## Form Class
169
3f82af0 Jeremy Bush Merge branch '3.0/develop' into 3.1/develop
zombor authored
170 If you used Form::open(), the default behavior has changed. It used to default to the current URI, but now an empty parameter will default to "/" (your home page).
cc41c84 Stephen George Docs: Adding note about moved log message type consts to upgrade guide. ...
sfgeorge authored
171
172 ## Logging
173
174 The log message level constants now belong to the Log class. If you are referencing those constants to invoke Kohana::$log->add( ... ) you will need to change the following:
175
176 - Kohana::ERROR -> Log::ERROR
177 - Kohana::DEBUG -> Log::DEBUG
178 - Kohana::INFO -> Log::INFO
Something went wrong with that request. Please try again.