Add a way for packagers to override some installation details
[mediawiki.git] / includes / Category.php
blob79870692df734b1e0e00ee5bc385645c48e6528a
1 <?php
2 /**
3 * Representation for a category.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
20 * @file
21 * @author Simetrical
24 /**
25 * Category objects are immutable, strictly speaking. If you call methods that change the database,
26 * like to refresh link counts, the objects will be appropriately reinitialized.
27 * Member variables are lazy-initialized.
29 * TODO: Move some stuff from CategoryPage.php to here, and use that.
31 class Category {
32 /** Name of the category, normalized to DB-key form */
33 private $mName = null;
34 private $mID = null;
35 /**
36 * Category page title
37 * @var Title
39 private $mTitle = null;
40 /** Counts of membership (cat_pages, cat_subcats, cat_files) */
41 private $mPages = null, $mSubcats = null, $mFiles = null;
43 private function __construct() { }
45 /**
46 * Set up all member variables using a database query.
47 * @return bool True on success, false on failure.
49 protected function initialize() {
50 if ( $this->mName === null && $this->mID === null ) {
51 throw new MWException( __METHOD__ . ' has both names and IDs null' );
52 } elseif ( $this->mID === null ) {
53 $where = array( 'cat_title' => $this->mName );
54 } elseif ( $this->mName === null ) {
55 $where = array( 'cat_id' => $this->mID );
56 } else {
57 # Already initialized
58 return true;
60 $dbr = wfGetDB( DB_SLAVE );
61 $row = $dbr->selectRow(
62 'category',
63 array( 'cat_id', 'cat_title', 'cat_pages', 'cat_subcats', 'cat_files' ),
64 $where,
65 __METHOD__
68 if ( !$row ) {
69 # Okay, there were no contents. Nothing to initialize.
70 if ( $this->mTitle ) {
71 # If there is a title object but no record in the category table, treat this as an empty category
72 $this->mID = false;
73 $this->mName = $this->mTitle->getDBkey();
74 $this->mPages = 0;
75 $this->mSubcats = 0;
76 $this->mFiles = 0;
78 return true;
79 } else {
80 return false; # Fail
84 $this->mID = $row->cat_id;
85 $this->mName = $row->cat_title;
86 $this->mPages = $row->cat_pages;
87 $this->mSubcats = $row->cat_subcats;
88 $this->mFiles = $row->cat_files;
90 # (bug 13683) If the count is negative, then 1) it's obviously wrong
91 # and should not be kept, and 2) we *probably* don't have to scan many
92 # rows to obtain the correct figure, so let's risk a one-time recount.
93 if ( $this->mPages < 0 || $this->mSubcats < 0 || $this->mFiles < 0 ) {
94 $this->refreshCounts();
97 return true;
101 * Factory function.
103 * @param $name Array: A category name (no "Category:" prefix). It need
104 * not be normalized, with spaces replaced by underscores.
105 * @return mixed Category, or false on a totally invalid name
107 public static function newFromName( $name ) {
108 $cat = new self();
109 $title = Title::makeTitleSafe( NS_CATEGORY, $name );
111 if ( !is_object( $title ) ) {
112 return false;
115 $cat->mTitle = $title;
116 $cat->mName = $title->getDBkey();
118 return $cat;
122 * Factory function.
124 * @param $title Title for the category page
125 * @return Category|bool on a totally invalid name
127 public static function newFromTitle( $title ) {
128 $cat = new self();
130 $cat->mTitle = $title;
131 $cat->mName = $title->getDBkey();
133 return $cat;
137 * Factory function.
139 * @param $id Integer: a category id
140 * @return Category
142 public static function newFromID( $id ) {
143 $cat = new self();
144 $cat->mID = intval( $id );
145 return $cat;
149 * Factory function, for constructing a Category object from a result set
151 * @param $row result set row, must contain the cat_xxx fields. If the fields are null,
152 * the resulting Category object will represent an empty category if a title object
153 * was given. If the fields are null and no title was given, this method fails and returns false.
154 * @param Title $title optional title object for the category represented by the given row.
155 * May be provided if it is already known, to avoid having to re-create a title object later.
156 * @return Category
158 public static function newFromRow( $row, $title = null ) {
159 $cat = new self();
160 $cat->mTitle = $title;
162 # NOTE: the row often results from a LEFT JOIN on categorylinks. This may result in
163 # all the cat_xxx fields being null, if the category page exists, but nothing
164 # was ever added to the category. This case should be treated linke an empty
165 # category, if possible.
167 if ( $row->cat_title === null ) {
168 if ( $title === null ) {
169 # the name is probably somewhere in the row, for example as page_title,
170 # but we can't know that here...
171 return false;
172 } else {
173 $cat->mName = $title->getDBkey(); # if we have a title object, fetch the category name from there
176 $cat->mID = false;
177 $cat->mSubcats = 0;
178 $cat->mPages = 0;
179 $cat->mFiles = 0;
180 } else {
181 $cat->mName = $row->cat_title;
182 $cat->mID = $row->cat_id;
183 $cat->mSubcats = $row->cat_subcats;
184 $cat->mPages = $row->cat_pages;
185 $cat->mFiles = $row->cat_files;
188 return $cat;
191 /** @return mixed DB key name, or false on failure */
192 public function getName() { return $this->getX( 'mName' ); }
194 /** @return mixed Category ID, or false on failure */
195 public function getID() { return $this->getX( 'mID' ); }
197 /** @return mixed Total number of member pages, or false on failure */
198 public function getPageCount() { return $this->getX( 'mPages' ); }
200 /** @return mixed Number of subcategories, or false on failure */
201 public function getSubcatCount() { return $this->getX( 'mSubcats' ); }
203 /** @return mixed Number of member files, or false on failure */
204 public function getFileCount() { return $this->getX( 'mFiles' ); }
207 * @return Title|bool Title for this category, or false on failure.
209 public function getTitle() {
210 if ( $this->mTitle ) return $this->mTitle;
212 if ( !$this->initialize() ) {
213 return false;
216 $this->mTitle = Title::makeTitleSafe( NS_CATEGORY, $this->mName );
217 return $this->mTitle;
221 * Fetch a TitleArray of up to $limit category members, beginning after the
222 * category sort key $offset.
223 * @param $limit integer
224 * @param $offset string
225 * @return TitleArray object for category members.
227 public function getMembers( $limit = false, $offset = '' ) {
228 $dbr = wfGetDB( DB_SLAVE );
230 $conds = array( 'cl_to' => $this->getName(), 'cl_from = page_id' );
231 $options = array( 'ORDER BY' => 'cl_sortkey' );
233 if ( $limit ) {
234 $options[ 'LIMIT' ] = $limit;
237 if ( $offset !== '' ) {
238 $conds[] = 'cl_sortkey > ' . $dbr->addQuotes( $offset );
241 return TitleArray::newFromResult(
242 $dbr->select(
243 array( 'page', 'categorylinks' ),
244 array( 'page_id', 'page_namespace', 'page_title', 'page_len',
245 'page_is_redirect', 'page_latest' ),
246 $conds,
247 __METHOD__,
248 $options
254 * Generic accessor
255 * @return bool
257 private function getX( $key ) {
258 if ( !$this->initialize() ) {
259 return false;
261 return $this-> { $key } ;
265 * Refresh the counts for this category.
267 * @return bool True on success, false on failure
269 public function refreshCounts() {
270 if ( wfReadOnly() ) {
271 return false;
274 # Note, we must use names for this, since categorylinks does.
275 if ( $this->mName === null ) {
276 if ( !$this->initialize() ) {
277 return false;
281 $dbw = wfGetDB( DB_MASTER );
282 $dbw->begin( __METHOD__ );
284 # Insert the row if it doesn't exist yet (e.g., this is being run via
285 # update.php from a pre-1.16 schema). TODO: This will cause lots and
286 # lots of gaps on some non-MySQL DBMSes if you run populateCategory.php
287 # repeatedly. Plus it's an extra query that's unneeded almost all the
288 # time. This should be rewritten somehow, probably.
289 $seqVal = $dbw->nextSequenceValue( 'category_cat_id_seq' );
290 $dbw->insert(
291 'category',
292 array(
293 'cat_id' => $seqVal,
294 'cat_title' => $this->mName
296 __METHOD__,
297 'IGNORE'
300 $cond1 = $dbw->conditional( 'page_namespace=' . NS_CATEGORY, 1, 'NULL' );
301 $cond2 = $dbw->conditional( 'page_namespace=' . NS_FILE, 1, 'NULL' );
302 $result = $dbw->selectRow(
303 array( 'categorylinks', 'page' ),
304 array( 'COUNT(*) AS pages',
305 "COUNT($cond1) AS subcats",
306 "COUNT($cond2) AS files"
308 array( 'cl_to' => $this->mName, 'page_id = cl_from' ),
309 __METHOD__,
310 'LOCK IN SHARE MODE'
312 $ret = $dbw->update(
313 'category',
314 array(
315 'cat_pages' => $result->pages,
316 'cat_subcats' => $result->subcats,
317 'cat_files' => $result->files
319 array( 'cat_title' => $this->mName ),
320 __METHOD__
322 $dbw->commit( __METHOD__ );
324 # Now we should update our local counts.
325 $this->mPages = $result->pages;
326 $this->mSubcats = $result->subcats;
327 $this->mFiles = $result->files;
329 return $ret;