Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 200 lines (166 sloc) 7.464 kB
49fea93 @daschl Shortening Headline!
daschl authored
1 Improve the code quality of your Lithium applications
2 =====================================================
9964cef @gwoo Updating readme. Addiing pre-commit hook.
gwoo authored
3 This project is a 100% Lithium based replacement for the [li3_qa](https://github.com/UnionOfRAD/li3_qa) library, which in turn depends on [phpca](https://github.com/UnionOfRAD/phpca).
7a6b7a5 @daschl Updating Readme
daschl authored
4
5ac9217 @blainesch Add the current travis build image to readme
blainesch authored
5 [![Build Status](https://secure.travis-ci.org/UnionOfRAD/li3_quality.png?branch=master)](http://travis-ci.org/UnionOfRAD/li3_quality)
6
7a6b7a5 @daschl Updating Readme
daschl authored
7 Here are some of the key features:
8
9 - Detect coding-standard violations.
10 - Find weak- or untested classes/methods.
11 - No external dependencies.
12 - Color-Highlighting.
13 - Integrates into the Lithium test dashboard.
14 - Runs on Windows without hassle.
15 - Cool shortcuts to ease your workflow.
151d6c0 @daschl Adding README
daschl authored
16
17 Installation
18 ------------
19 Clone the repository in your libraries path and then add this line to the `config/bootstrap/libraries.php` file:
20
21 ```php
43ed39a @daschl Small readme alignment error
daschl authored
22 /**
23 * Add some plugins:
24 */
25 Libraries::add('li3_quality');
151d6c0 @daschl Adding README
daschl authored
26 ```
9964cef @gwoo Updating readme. Addiing pre-commit hook.
gwoo authored
27 If you open the test dashboard (under `/test` in your browser), you can should have an additional `Syntax` button to check the files directly in your browser.
7a6b7a5 @daschl Updating Readme
daschl authored
28
151d6c0 @daschl Adding README
daschl authored
29 Usage
30 -----
7a6b7a5 @daschl Updating Readme
daschl authored
31 If you run the `li3` command from your console, you'll now find the `syntax` command with its various params:
151d6c0 @daschl Adding README
daschl authored
32
33 ```bash
43ed39a @daschl Small readme alignment error
daschl authored
34 $ li3 quality
7a6b7a5 @daschl Updating Readme
daschl authored
35 Lithium console started in the development environment. Use the --env=environment key to alter this.
43ed39a @daschl Small readme alignment error
daschl authored
36 USAGE
7a6b7a5 @daschl Updating Readme
daschl authored
37 li3 quality syntax
38 li3 quality documented
39 li3 quality coverage
43ed39a @daschl Small readme alignment error
daschl authored
40 DESCRIPTION
7a6b7a5 @daschl Updating Readme
daschl authored
41 The Quality command helps you to run static code analysis on your codebase.
43ed39a @daschl Small readme alignment error
daschl authored
42 OPTIONS
7a6b7a5 @daschl Updating Readme
daschl authored
43 syntax
44 Checks the syntax of your class files through static code analysis.
45 documented
96f17da @gwoo Updating readme to use --library. `Quality` looks for the default lib…
gwoo authored
46 Checks for undocumented classes or methods inside the library.
7a6b7a5 @daschl Updating Readme
daschl authored
47 coverage
48 Lists code coverage for a given threshold (100 by default).
96f17da @gwoo Updating readme to use --library. `Quality` looks for the default lib…
gwoo authored
49 --library=<>
50 The library to run the quality checks on.
7a6b7a5 @daschl Updating Readme
daschl authored
51 --silent=<>
52 If `--silent` is used, only failures are shown.
53 --threshold=<>
54 If `--slient NUM` is used, only classes below this coverage are shown.
151d6c0 @daschl Adding README
daschl authored
55 ```
56
7a6b7a5 @daschl Updating Readme
daschl authored
57 The "syntax" command
58 --------------------
59 If you just run it with `li3 quality syntax`, it will run all rules against your `app` library.
151d6c0 @daschl Adding README
daschl authored
60
61 ```bash
43ed39a @daschl Small readme alignment error
daschl authored
62 $ li3 quality syntax
63 --------------------
64 Lithium Syntax Check
65 --------------------
66 Performing 16 rules on 6 classes.
67 [FAIL] app\models\Authors
68 Line Position Violation
69 ---- -------- ---------
70 7 1 Trailing whitespace found
71 [OK] app\models\Groups
72 [OK] app\models\Posts
73 [FAIL] app\controllers\HelloWorldController
74 Line Position Violation
75 ---- -------- ---------
76 17 - Function "to_string" is not in camelBack style
77 21 - Function "to_json" is not in camelBack style
78 24 1 Trailing whitespace found
79 [FAIL] app\controllers\PagesController
80 Line Position Violation
81 ---- -------- ---------
82 32 1 Trailing whitespace found
83 34 1 Trailing whitespace found
84 28 - Protected Method "view" does not start with "_"
85 33 - Protected Method "foobar" does not start with "_"
151d6c0 @daschl Adding README
daschl authored
86 ```
87
921cb62 @mehlah Add a section to README about custom syntax rules
mehlah authored
88 If you have lots of files to check (for example if you test against the lithium core), you can pass the `--silent` option to only show errors. The `--library` param allows you to run the checks against a different library:
151d6c0 @daschl Adding README
daschl authored
89
90 ```bash
96f17da @gwoo Updating readme to use --library. `Quality` looks for the default lib…
gwoo authored
91 $ li3 quality syntax --silent --library=lithium
43ed39a @daschl Small readme alignment error
daschl authored
92 --------------------
93 Lithium Syntax Check
94 --------------------
95 Performing 16 rules on 375 classes.
96 [FAIL] lithium\tests\cases\net\http\RouteTest
97 Line Position Violation
98 ---- -------- ---------
99 383 103 Maximum line length exceeded
100 [FAIL] lithium\tests\cases\console\command\LibraryTest
101 Line Position Violation
102 ---- -------- ---------
103 241 101 Maximum line length exceeded
104 [FAIL] lithium\test\Unit
105 Line Position Violation
106 ---- -------- ---------
107 1017 102 Maximum line length exceeded
108 [FAIL] lithium\data\Entity
109 Line Position Violation
110 ---- -------- ---------
111 379 111 Maximum line length exceeded
112 381 110 Maximum line length exceeded
151d6c0 @daschl Adding README
daschl authored
113 ```
114
921cb62 @mehlah Add a section to README about custom syntax rules
mehlah authored
115 #### Custom rules set
116
117 By default, `li3 quality syntax` command looks for a set of rules to apply, defined in `{checked-library}/test/rules.json`. Otherwise it uses [the default rules set](https://github.com/UnionOfRAD/li3_quality/blob/master/test/defaultRules.json).
118 You can customize this configuration file to suit your own quality standards, by removing unwanted rules, or by adding your own rules classes at `{:library}/extensions/test/rules/YourCustomRule.php`.
119
9964cef @gwoo Updating readme. Addiing pre-commit hook.
gwoo authored
120 GIT Pre Commit Hook
121 --------------------
122
123 This pre commit hook is based upon the example found in `.git/hooks/pre-commit.sample`. Copy the sample script to `/path/to/project/.git/hooks/pre-commit` and make it executable. Then, replace the code in the script with the code shown below and adjust the paths to Lithium QA and the li3 command.
124
125 ```
126 cd /path/to/project
127 cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
128 chmod a+x .git/hooks/pre-commit
129 ```
130
f8d581d @gwoo Found a typo in readme.
gwoo authored
131 Now add the following code to .git/hooks/pre-commit and adjust the `APP` and `LI3` values.
9964cef @gwoo Updating readme. Addiing pre-commit hook.
gwoo authored
132
133 ```bash
134 #!/bin/sh
135
136 APP=/path/to/li3_quality_enabled/app/
137 LI3=/path/to/lithium/libraries/lithium/console/li3
138
139 if git-rev-parse --verify HEAD >/dev/null 2>&1
140 then
141 AGAINST=HEAD
142 else
143 # Initial commit: diff against an empty tree object
144 AGAINST=4b825dc642cb6eb9a060e54bf8d69288fbee4904
145 fi
146
147 EXIT_STATUS=0
148 PROJECT=`pwd`
149
150 for FILE in `git diff-index --cached --name-only --diff-filter=AM ${AGAINST}`
151 do
152 cd ${APP} && ${LI3} quality syntax ${PROJECT}/${FILE}
153 test $? != 0 && EXIT_STATUS=1
154 done
155
156 exit ${EXIT_STATUS}
157 ```
158
159 Now when committing each file the syntax is checked. The commit is aborted if a check failed. If you don't want to have the hook run on commit pass the `--no-verify` option to git commit.
151d6c0 @daschl Adding README
daschl authored
160
7a6b7a5 @daschl Updating Readme
daschl authored
161 The "coverage" command
162 ----------------------
163 With `li3 quality coverage` you can get a summary of how well your classes are covered with tests. This makes use of some `xdebug` functions, so make sure to have it installed.
164
165 ```bash
166 $ li3 quality coverage
167 ---------------------
168 Lithium Code Coverage
169 ---------------------
170 Checking coverage on 6 classes.
171 no test | n/a | app\models\Authors
172 no test | n/a | app\models\Groups
173 no test | n/a | app\models\Posts
174 no test | n/a | app\controllers\HelloWorldController
175 no test | n/a | app\controllers\PagesController
176 no test | n/a | app\controllers\PostsController
177 ```
178
96f17da @gwoo Updating readme to use --library. `Quality` looks for the default lib…
gwoo authored
179 You can also reuse the `--library` argument as well. In addition, this command provides an optional `--threshold` argument that only displays coverage below the given amount. This defaults to 100, so all classes will be shown. If you have coloring on your shell (likely not on windows), then the classes are colored to reflect the coverage policy of the Lithium framework (0% or no test is red, 85% or higher is green and the rest is yellow).
7a6b7a5 @daschl Updating Readme
daschl authored
180
181 The "documented" command
182 ------------------------
183 This command needs to be implemented.
184
151d6c0 @daschl Adding README
daschl authored
185 Planned
186 -------
10a4b5e @gavD Add test for superglobals
gavD authored
187 See the issue tracker for all tickets that are currently marked as "enhancement".
188
189 Troubleshooting
190 ===============
191
192 Can't find files
193 ----------------
194
195 Please make sure you are supplying the library parameter to match the root namespace of your project, e.g.:
196
197 ```bash
198 libraries/lithium/console/li3 quality syntax --library=myapp
199 ```
Something went wrong with that request. Please try again.