Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 316 lines (233 sloc) 8.669 kB
9160f25 @Thinkscape Add docs.
Thinkscape authored
1 ZF2 Tool Diagnostics
2 ==========================
3
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
4 1. [Available checks](#available-checks)
5 2. [Running diagnostics in console](#running-diagnostics-in-console)
6 3. [Running diagnostics in web browser](#running-diagnostics-in-web-browser)
7 4. [What is a check?](#what-is-a-check)
8 5. [Adding checks to your module](#adding-checks-to-your-module)
9 6. [Checks in config files](#checks-in-config-files)
10 7. [Using built-in diagnostics checks](#using-built-in-diagnostics-checks)
11 8. [Providing debug information in checks](#providing-debug-information-in-checks)
12
13 ## Available checks
14
d89b662 @Thinkscape CS Fixes.
Thinkscape authored
15 * All checks from [ZendDiagnostics](https://github.com/zendframework/ZendDiagnostics#zenddiagnostics)
3c09888 @Thinkscape Fix TOC.
Thinkscape authored
16
17 ## Running diagnostics in console
9160f25 @Thinkscape Add docs.
Thinkscape authored
18
19 After installing ZF2 tool, you can run application diagnostics with the following console command:
20
21 php public/index.php diag
22
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
23 This will run the default set of diag checks and in case of trouble, display any errors or warnings.
9160f25 @Thinkscape Add docs.
Thinkscape authored
24 ![Running diag in console](img/simple-run.png)
25
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
26 To display additional information on the checks performed, you can run diagnostics in verbose mode using
a7e0c62 @Thinkscape Increase unit tests coverage for Test\ to 99%, fix CS fixes, fix typos.
Thinkscape authored
27 `--verbose` or `-v` switches:
9160f25 @Thinkscape Add docs.
Thinkscape authored
28
29 php public/index.php diag -v
30
31 ![Verbose mode diagnostics](img/verbose-run.png)
32
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
33 Some checks will also produce debug information, which you can display with `--debug` switch:
9160f25 @Thinkscape Add docs.
Thinkscape authored
34
35 # Run diagnostics in "debug" mode
36 php public/index.php diag --debug
37
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
38 You could also specify which checks you want to run (which module to check):
9160f25 @Thinkscape Add docs.
Thinkscape authored
39
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
40 # Run only checks included in Application module
9160f25 @Thinkscape Add docs.
Thinkscape authored
41 php public/index.php diag Application
42
3c09888 @Thinkscape Fix TOC.
Thinkscape authored
43
44 ## Running diagnostics in web browser
9160f25 @Thinkscape Add docs.
Thinkscape authored
45
46 In order to enable diagnostics in browser, copy the included `config/zftool.global.php.dist` file to
47 your `config/autoload/` directory and rename it to `zftool.global.php`. Now open the file and uncomment
48 the `router => array()` section. The default URL for diagnostics is simply:
49
50 http://yourwebsite/diagnostics
51
52 You can always change it to anything you like by editing the above config file.
53
54 ![Browser-based diagnostics](img/browser-run.png)
55
3c09888 @Thinkscape Fix TOC.
Thinkscape authored
56
57
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
58 ## What is a check?
9160f25 @Thinkscape Add docs.
Thinkscape authored
59
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
60 A check is simply:
9160f25 @Thinkscape Add docs.
Thinkscape authored
61
62 * Any function (anonymous, named, method), or
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
63 * Any class implementing `ZFTool\Diagnostics\Check\CheckInterface`
9160f25 @Thinkscape Add docs.
Thinkscape authored
64
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
65 A check returns:
9160f25 @Thinkscape Add docs.
Thinkscape authored
66
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
67 * `true` which means check passed OK,
68 * `false` which means check failed,
9160f25 @Thinkscape Add docs.
Thinkscape authored
69 * a `string` with warning message,
70 * or instance of `ZFTool\Diagnostics\Result`, including Success, Failure, Warning.
71
72
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
73 ## Adding checks to your module
9160f25 @Thinkscape Add docs.
Thinkscape authored
74
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
75 The simplest way to add checks is to write `getDiagnostics()` method in your module main class. For example, we could
76 add the following checks to our `modules/Application/Module.php` file:
9160f25 @Thinkscape Add docs.
Thinkscape authored
77
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
78 ````php
79 <?php
80 namespace Application;
81
82 class Module {
83 // [...]
84
85 /**
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
86 * This method should return an array of checks,
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
87 */
88 public function getDiagnostics()
89 {
90 return array(
91 'Memcache present' => function(){
92 return function_exists('memcache_add');
93 },
94 'Cache directory exists' => function() {
95 return file_exists('data/cache') && is_dir('data/cache');
96 }
97 );
9160f25 @Thinkscape Add docs.
Thinkscape authored
98 }
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
99 }
100 ````
9160f25 @Thinkscape Add docs.
Thinkscape authored
101
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
102 The returned array should contain pairs of a `label => check`. The label can be any string and will only be
103 used as a description of the tested requirement. The `check` can be a callable, a function or a string, which
104 will automatically be expanded. The following chapter describes all available methods of declaring checks.
9160f25 @Thinkscape Add docs.
Thinkscape authored
105
a263e6e @Thinkscape Fix typos, add toc.
Thinkscape authored
106
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
107 ## Checks in config files
a263e6e @Thinkscape Fix typos, add toc.
Thinkscape authored
108
9160f25 @Thinkscape Add docs.
Thinkscape authored
109
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
110 The second method is to define checks in config files which will be lazy-loaded as needed. Diagnostic
9160f25 @Thinkscape Add docs.
Thinkscape authored
111 component can understand the following types of definitions:
112
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
113 ### Check function name
9160f25 @Thinkscape Add docs.
Thinkscape authored
114
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
115 The simplest form of a check is a "callable", a function or a method. Here are a few examples:
9160f25 @Thinkscape Add docs.
Thinkscape authored
116
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
117 ````php
118 <?php
119 // modules/Application/config/module.config.php
120 return array(
121 'diagnostics' => array(
122
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
123 // "application" check group
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
124 'application' => array(
125 // invoke static method Application\Module::checkEnvironment()
126 'Check environment' => array('Application\Module', 'checkEnvironment'),
127
128 // invoke php built-in function with a parameter
129 'Check if public dir exists' => array('file_exists', 'public/'),
130
131 // invoke a static method with 2 parameters
132 'Check paths' => array(
133 array('Application\Module', 'checkPaths'),
134 'foo/',
a263e6e @Thinkscape Fix typos, add toc.
Thinkscape authored
135 'bar/'
9160f25 @Thinkscape Add docs.
Thinkscape authored
136 )
137 )
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
138 )
139 );
140 ````
9160f25 @Thinkscape Add docs.
Thinkscape authored
141
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
142 ### Check class name
9160f25 @Thinkscape Add docs.
Thinkscape authored
143
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
144 Assuming we have written following check class:
9160f25 @Thinkscape Add docs.
Thinkscape authored
145
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
146 ````php
147 <?php
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
148 namespace Application\Check;
9160f25 @Thinkscape Add docs.
Thinkscape authored
149
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
150 class is64bit extends ZFTool\Diagnostics\Check\AbstractCheck
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
151 {
152 public function run()
9160f25 @Thinkscape Add docs.
Thinkscape authored
153 {
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
154 return PHP_INT_SIZE === 8;
9160f25 @Thinkscape Add docs.
Thinkscape authored
155 }
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
156 }
157 ````
9160f25 @Thinkscape Add docs.
Thinkscape authored
158
159 We can now use it in our Application configuration file in the following way:
160
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
161 ````php
162 <?php
163 // modules/Application/config/module.config.php
164 return array(
165 'diagnostics' => array(
166 'application' => array(
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
167 'Verify that this system is 64bit' => 'Application\Check\is64bit'
9160f25 @Thinkscape Add docs.
Thinkscape authored
168 )
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
169 )
170 );
171 ````
9160f25 @Thinkscape Add docs.
Thinkscape authored
172
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
173 It is also possible to provide constructor parameters for check instances, like so:
174
175 ````php
176 <?php
177 namespace Application\Check;
178
179 class EnvironmentTest extends ZFTool\Diagnostics\Check\AbstractCheck
180 {
181 // [...]
182 }
183 ````
9160f25 @Thinkscape Add docs.
Thinkscape authored
184
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
185 ````php
186 <?php
187 // modules/Application/config/module.config.php
188 return array(
189 'diagnostics' => array(
190 'application' => array(
191 // equivalent of constructing new EnvironmentTest("production", 15);
192 'Verify environment' => array(
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
193 'Application\Check\is64bit',
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
194 'production',
195 15
9160f25 @Thinkscape Add docs.
Thinkscape authored
196 )
197 )
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
198 )
199 );
200 ````
9160f25 @Thinkscape Add docs.
Thinkscape authored
201
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
202 ### Check instance fetched from Service Manager
9160f25 @Thinkscape Add docs.
Thinkscape authored
203
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
204 If we define the check as a string, the diag component will attempt to fetch the check from
205 Application Service Manager. For example, we could have the following check class:
9160f25 @Thinkscape Add docs.
Thinkscape authored
206
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
207 ````php
208 <?php
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
209 namespace Application\Check;
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
210
211 use Zend\ServiceManager\ServiceLocatorAwareInterface;
212 use Zend\ServiceManager\ServiceLocatorInterface;
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
213 use ZFTool\Diagnostics\Check\AbstractTest;
9160f25 @Thinkscape Add docs.
Thinkscape authored
214
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
215 class CheckUserModule extends AbstractTest implements ServiceLocatorAwareInterface
216 {
217 protected $sl;
9160f25 @Thinkscape Add docs.
Thinkscape authored
218
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
219 public function run()
9160f25 @Thinkscape Add docs.
Thinkscape authored
220 {
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
221 return $this->getServiceLocator()->has('zfcuser');
9160f25 @Thinkscape Add docs.
Thinkscape authored
222 }
223
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
224 public function setServiceLocator(ServiceLocatorInterface $sl)
225 {
226 $this->sl = $sl;
227 }
228
229 public function getServiceLocator()
230 {
231 return $this->sl;
232 }
233 }
234 ````
235
9160f25 @Thinkscape Add docs.
Thinkscape authored
236 Now we just have to add proper definition to Service Manager and then diagnostics.
237
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
238
239 ````php
240 <?php
241 // modules/Application/config/module.config.php
242 return array(
243 service_manager' => array(
244 invokables' => array(
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
245 'CheckUserModuleTest' => 'Application\check\CheckUserModule',
9160f25 @Thinkscape Add docs.
Thinkscape authored
246 ),
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
247 ),
9160f25 @Thinkscape Add docs.
Thinkscape authored
248
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
249 'diagnostics' => array(
250 'application' => array(
251 'Check if user module is loaded' => 'CheckUserModuleTest'
9160f25 @Thinkscape Add docs.
Thinkscape authored
252 )
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
253 )
254 );
255 ````
256
9160f25 @Thinkscape Add docs.
Thinkscape authored
257
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
258 ## Using built-in diagnostics checks
9160f25 @Thinkscape Add docs.
Thinkscape authored
259
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
260 ZFTool uses a bundle of general-purpose checks from
261 [ZendDiagnostics](https://github.com/zendframework/ZendDiagnostics#zenddiagnostics) but also provides ZF2-specific
262 classes.
9160f25 @Thinkscape Add docs.
Thinkscape authored
263
264
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
265 ## Providing debug information in checks
9160f25 @Thinkscape Add docs.
Thinkscape authored
266
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
267 A check function or class can return an instance of `Success`, `Failure` or `Warning` providing detailed information
268 on the check performed and its result:
9160f25 @Thinkscape Add docs.
Thinkscape authored
269
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
270 ````php
9160f25 @Thinkscape Add docs.
Thinkscape authored
271 $success = new ZFTool\Diagnostics\Result\Success( $message, $debugData )
272 $failure = new ZFTool\Diagnostics\Result\Failure( $message, $debugData )
273 $warning = new ZFTool\Diagnostics\Result\Warning( $message, $debugData )
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
274 ````
9160f25 @Thinkscape Add docs.
Thinkscape authored
275
182f1f8 @Thinkscape Refactor for ZendDiagnostics 1.0, fixes and enhancements.
Thinkscape authored
276 Below is an example of a module-defined checks that return various responses:
9160f25 @Thinkscape Add docs.
Thinkscape authored
277
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
278 ````php
279 <?php
280 // modules/Application/Module.php
281
282 namespace Application;
283
284 use ZFTool\Diagnostics\Result\Success;
285 use ZFTool\Diagnostics\Result\Failure;
286 use ZFTool\Diagnostics\Result\Warning;
287
288 class Module {
289 // [...]
290
291 public function getDiagnostics()
292 {
293 return array(
294 'Check PHP extensions' => function(){
e6f885e @AV4TAr Syntax error fixes, missing ; and )
AV4TAr authored
295 if (!extension_loaded('mbstring')) {
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
296 return new Failure(
297 'MB string is required for this module to work',
298 get_loaded_extensions()
e6f885e @AV4TAr Syntax error fixes, missing ; and )
AV4TAr authored
299 );
9160f25 @Thinkscape Add docs.
Thinkscape authored
300 }
301
948449a @Thinkscape Add fence code blocks to docs.
Thinkscape authored
302 if (!extension_loaded('apc')) {
303 return new Warning(
304 'APC extension is not loaded. It is highly recommended for performance.',
305 get_loaded_extensions()
306 );
307 }
308
309 return new Success('Everything in order...');
310 }
311 );
312 }
313 }
314 ````
9160f25 @Thinkscape Add docs.
Thinkscape authored
315
Something went wrong with that request. Please try again.