| 1 | <?php |
| 2 | /* -*- tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ |
| 3 | /* |
| 4 | # ***** BEGIN LICENSE BLOCK ***** |
| 5 | # This file is part of InDefero, an open source project management application. |
| 6 | # Copyright (C) 2008 Céondo Ltd and contributors. |
| 7 | # |
| 8 | # InDefero is free software; you can redistribute it and/or modify |
| 9 | # it under the terms of the GNU General Public License as published by |
| 10 | # the Free Software Foundation; either version 2 of the License, or |
| 11 | # (at your option) any later version. |
| 12 | # |
| 13 | # InDefero is distributed in the hope that it will be useful, |
| 14 | # but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 15 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 16 | # GNU General Public License for more details. |
| 17 | # |
| 18 | # You should have received a copy of the GNU General Public License |
| 19 | # along with this program; if not, write to the Free Software |
| 20 | # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA |
| 21 | # |
| 22 | # ***** END LICENSE BLOCK ***** */ |
| 23 | |
| 24 | /** |
| 25 | * Manage differents SCM systems. |
| 26 | * |
| 27 | * This is the base class with the different required methods to be |
| 28 | * implemented by the SCMs. Each SCM backend need to extend this |
| 29 | * class. We are not using an interface because this is not really |
| 30 | * needed. |
| 31 | * |
| 32 | * The philosophy behind the interface is not to provide a wrapper |
| 33 | * around the different SCMs but to provide methods to retrieve in the |
| 34 | * most efficient way the informations to be displayed/needed in the |
| 35 | * web interface. This means that each SCM can use the best options, |
| 36 | * including caching to retrieve the informations. |
| 37 | * |
| 38 | * Note on caching: You must not cache ephemeral information like the |
| 39 | * changelog, but you can cache the commit info (except with |
| 40 | * subversion where you can change commit info...). It is ok to do |
| 41 | * some caching for the lifetime of the IDF_Scm object, for example |
| 42 | * not to retrieve several times the list of branches, etc. |
| 43 | * |
| 44 | * All the output of the methods must be serializable. This means that |
| 45 | * if you are parsing XML you need to correctly cast the results as |
| 46 | * string when needed. |
| 47 | */ |
| 48 | class IDF_Scm |
| 49 | { |
| 50 | /** |
| 51 | * String template for consistent error messages. |
| 52 | */ |
| 53 | public $error_tpl = 'Error command "%s" returns code %d and output: %s'; |
| 54 | |
| 55 | /** |
| 56 | * Path to the repository. |
| 57 | */ |
| 58 | public $repo = ''; |
| 59 | |
| 60 | /** |
| 61 | * Corresponding project object. |
| 62 | */ |
| 63 | public $project = null; |
| 64 | |
| 65 | /** |
| 66 | * Cache storage. |
| 67 | * |
| 68 | * It must only be used to store data for the lifetime of the |
| 69 | * object. For example if you need to get the list of branches in |
| 70 | * several functions, better to try to get from the cache first. |
| 71 | */ |
| 72 | protected $cache = array(); |
| 73 | |
| 74 | |
| 75 | /** |
| 76 | * Returns an instance of the correct scm backend object. |
| 77 | * |
| 78 | * @param IDF_Project |
| 79 | * @return Object |
| 80 | */ |
| 81 | public static function get($project) |
| 82 | { |
| 83 | // Get scm type from project conf ; defaults to git |
| 84 | // We will need to cache the factory |
| 85 | $scm = $project->getConf()->getVal('scm', 'git'); |
| 86 | $scms = Pluf::f('allowed_scm'); |
| 87 | return call_user_func(array($scms[$scm], 'factory'), $project); |
| 88 | } |
| 89 | |
| 90 | /** |
| 91 | * Run exec and log some information. |
| 92 | * |
| 93 | * @param $caller Calling method |
| 94 | * @param $cmd Command to run |
| 95 | * @param &$out Array of output |
| 96 | * @param &$return Return value |
| 97 | * @return string Last line of the command |
| 98 | */ |
| 99 | public static function exec($caller, $cmd, &$out=null, &$return=null) |
| 100 | { |
| 101 | Pluf_Log::stime('timer'); |
| 102 | $ret = exec($cmd, $out, $return); |
| 103 | Pluf_Log::perf(array($caller, $cmd, Pluf_Log::etime('timer', 'total_exec'))); |
| 104 | Pluf_Log::debug(array($caller, $cmd, $out)); |
| 105 | Pluf_Log::inc('exec_calls'); |
| 106 | return $ret; |
| 107 | } |
| 108 | |
| 109 | /** |
| 110 | * Run shell_exec and log some information. |
| 111 | * |
| 112 | * @param $caller Calling method |
| 113 | * @param $cmd Command to run |
| 114 | * @return string The output |
| 115 | */ |
| 116 | public static function shell_exec($caller, $cmd) |
| 117 | { |
| 118 | Pluf_Log::stime('timer'); |
| 119 | $ret = shell_exec($cmd); |
| 120 | Pluf_Log::perf(array($caller, $cmd, Pluf_Log::etime('timer', 'total_exec'))); |
| 121 | Pluf_Log::debug(array($caller, $cmd, $ret)); |
| 122 | Pluf_Log::inc('exec_calls'); |
| 123 | return $ret; |
| 124 | } |
| 125 | |
| 126 | /** |
| 127 | * Return the size of the repository in bytes. |
| 128 | * |
| 129 | * @return int Size in byte, -1 if the size cannot be evaluated. |
| 130 | */ |
| 131 | public function getRepositorySize() |
| 132 | { |
| 133 | return -1; |
| 134 | } |
| 135 | |
| 136 | /** |
| 137 | * Returns the URL of the git daemon. |
| 138 | * |
| 139 | * @param IDF_Project |
| 140 | * @return string URL |
| 141 | */ |
| 142 | public static function getAnonymousAccessUrl($project) |
| 143 | { |
| 144 | throw new Pluf_Exception_NotImplemented(); |
| 145 | } |
| 146 | |
| 147 | /** |
| 148 | * Returns the URL for SSH access |
| 149 | * |
| 150 | * @param IDF_Project |
| 151 | * @param Pluf_User |
| 152 | * @return string URL |
| 153 | */ |
| 154 | public static function getAuthAccessUrl($project, $user) |
| 155 | { |
| 156 | throw new Pluf_Exception_NotImplemented(); |
| 157 | } |
| 158 | |
| 159 | /** |
| 160 | * Check if the backend is available for display. |
| 161 | * |
| 162 | * @return bool Available |
| 163 | */ |
| 164 | public function isAvailable() |
| 165 | { |
| 166 | throw new Pluf_Exception_NotImplemented(); |
| 167 | } |
| 168 | |
| 169 | /** |
| 170 | * Check if a revision or commit is valid. |
| 171 | * |
| 172 | * @param string Revision or commit |
| 173 | * @return bool |
| 174 | */ |
| 175 | public function isValidRevision($rev) |
| 176 | { |
| 177 | throw new Pluf_Exception_NotImplemented(); |
| 178 | } |
| 179 | |
| 180 | /** |
| 181 | * Returns in which branches a commit/path is. |
| 182 | * |
| 183 | * A commit can be in several branches and some of the SCMs are |
| 184 | * managing branches using subfolders (like Subversion). |
| 185 | * |
| 186 | * This means that to know in which branch we are at the moment, |
| 187 | * one needs to have both the path and the commit. |
| 188 | * |
| 189 | * @param string Commit |
| 190 | * @param string Path |
| 191 | * @return array Branches |
| 192 | */ |
| 193 | public function inBranches($commit, $path) |
| 194 | { |
| 195 | throw new Pluf_Exception_NotImplemented(); |
| 196 | } |
| 197 | |
| 198 | /** |
| 199 | * Returns the list of branches. |
| 200 | * |
| 201 | * The return value must be a branch indexed array with the |
| 202 | * optional path to access the branch as value. For example with |
| 203 | * git you would get (note that some people are using / in the |
| 204 | * name of their git branches): |
| 205 | * |
| 206 | * <pre> |
| 207 | * array('master' => '', |
| 208 | * 'foo-branch' => '', |
| 209 | * 'design/feature1' => '') |
| 210 | * </pre> |
| 211 | * |
| 212 | * But with Subversion, as the branches are managed as subfolder |
| 213 | * with a special folder for trunk, you would get something like: |
| 214 | * |
| 215 | * <pre> |
| 216 | * array('trunk' => 'trunk', |
| 217 | * 'foo-branch' => 'branches/foo-branch',) |
| 218 | * </pre> |
| 219 | * |
| 220 | * @return array Branches |
| 221 | */ |
| 222 | public function getBranches() |
| 223 | { |
| 224 | throw new Pluf_Exception_NotImplemented(); |
| 225 | } |
| 226 | |
| 227 | /** |
| 228 | * Returns the list of tags. |
| 229 | * |
| 230 | * The format is the same as for the branches. |
| 231 | * |
| 232 | * @see self::getBranches() |
| 233 | * |
| 234 | * @return array Tags |
| 235 | */ |
| 236 | public function getTags() |
| 237 | { |
| 238 | throw new Pluf_Exception_NotImplemented(); |
| 239 | } |
| 240 | |
| 241 | /** |
| 242 | * Returns in which tags a commit/path is. |
| 243 | * |
| 244 | * A commit can be in several tags and some of the SCMs are |
| 245 | * managing tags using subfolders (like Subversion). |
| 246 | * |
| 247 | * This means that to know in which tag we are at the moment, |
| 248 | * one needs to have both the path and the commit. |
| 249 | * |
| 250 | * @param string Commit |
| 251 | * @param string Path |
| 252 | * @return array Tags |
| 253 | */ |
| 254 | public function inTags($commit, $path) |
| 255 | { |
| 256 | throw new Pluf_Exception_NotImplemented(); |
| 257 | } |
| 258 | |
| 259 | /** |
| 260 | * Returns the main branch. |
| 261 | * |
| 262 | * The main branch is the one displayed by default. For example |
| 263 | * master, trunk or tip. |
| 264 | * |
| 265 | * @return string |
| 266 | */ |
| 267 | public function getMainBranch() |
| 268 | { |
| 269 | throw new Pluf_Exception_NotImplemented(); |
| 270 | } |
| 271 | |
| 272 | /** |
| 273 | * Returns the list of files in a given folder. |
| 274 | * |
| 275 | * The list is an array of standard class objects with attributes |
| 276 | * for each file/directory/external element. |
| 277 | * |
| 278 | * This is the most important method of the SCM backend as this is |
| 279 | * the one conveying the speed feeling of the application. All the |
| 280 | * dirty optimization tricks are allowed there. |
| 281 | * |
| 282 | * @param string Revision or commit |
| 283 | * @param string Folder ('/') |
| 284 | * @param string Branch (null) |
| 285 | * @return array |
| 286 | */ |
| 287 | public function getTree($rev, $folder='/', $branch=null) |
| 288 | { |
| 289 | throw new Pluf_Exception_NotImplemented(); |
| 290 | } |
| 291 | |
| 292 | /** |
| 293 | * Get commit details. |
| 294 | * |
| 295 | * @param string Commit or revision number |
| 296 | * @param bool Get commit diff (false) |
| 297 | * @return stdClass |
| 298 | */ |
| 299 | public function getCommit($commit, $getdiff=false) |
| 300 | { |
| 301 | throw new Pluf_Exception_NotImplemented(); |
| 302 | } |
| 303 | |
| 304 | /** |
| 305 | * Get latest changes. |
| 306 | * |
| 307 | * It default to the main branch. If possible you should code in a |
| 308 | * way to avoid repetitive calls to getCommit. Try to be |
| 309 | * efficient. |
| 310 | * |
| 311 | * @param string Branch (null) |
| 312 | * @param int Number of changes (25) |
| 313 | * @return array List of commits |
| 314 | */ |
| 315 | public function getChangeLog($branch=null, $n=10) |
| 316 | { |
| 317 | throw new Pluf_Exception_NotImplemented(); |
| 318 | } |
| 319 | |
| 320 | /** |
| 321 | * Given the string describing the author from the log find the |
| 322 | * author in the database. |
| 323 | * |
| 324 | * If the input is an array, it will return an array of results. |
| 325 | * |
| 326 | * @param mixed string/array Author |
| 327 | * @return mixed Pluf_User or null or array |
| 328 | */ |
| 329 | public function findAuthor($author) |
| 330 | { |
| 331 | throw new Pluf_Exception_NotImplemented(); |
| 332 | } |
| 333 | |
| 334 | /** |
| 335 | * Given a revision and a file path, retrieve the file content. |
| 336 | * |
| 337 | * The $cmd_only parameter is to only request the command that is |
| 338 | * used to get the file content. This is used when downloading a |
| 339 | * file at a given revision as it can be passed to a |
| 340 | * Pluf_HTTP_Response_CommandPassThru reponse. This allows to |
| 341 | * stream a large response without buffering it in memory. |
| 342 | * |
| 343 | * The file definition is coming from getPathInfo(). |
| 344 | * |
| 345 | * @see self::getPathInfo() |
| 346 | * |
| 347 | * @param stdClass File definition |
| 348 | * @param bool Returns command only (false) |
| 349 | * @return string File content |
| 350 | */ |
| 351 | public function getFile($def, $cmd_only=false) |
| 352 | { |
| 353 | throw new Pluf_Exception_NotImplemented(); |
| 354 | } |
| 355 | |
| 356 | /** |
| 357 | * Get information about a file or a path. |
| 358 | * |
| 359 | * @param string File or path |
| 360 | * @param string Revision (null) |
| 361 | * @return mixed False or stdClass with info |
| 362 | */ |
| 363 | public function getPathInfo($file, $rev=null) |
| 364 | { |
| 365 | throw new Pluf_Exception_NotImplemented(); |
| 366 | } |
| 367 | |
| 368 | /** |
| 369 | * Given a revision and possible path returns additional properties. |
| 370 | * |
| 371 | * @param string Revision |
| 372 | * @param string Path ('') |
| 373 | * @return mixed null or array of properties |
| 374 | */ |
| 375 | public function getProperties($rev, $path='') |
| 376 | { |
| 377 | return null; |
| 378 | } |
| 379 | |
| 380 | /** |
| 381 | * Generate the command to create a zip archive at a given commit. |
| 382 | * |
| 383 | * @param string Commit |
| 384 | * @param string Prefix ('repository/') |
| 385 | * @return string Command |
| 386 | */ |
| 387 | public function getArchiveCommand($commit, $prefix='repository/') |
| 388 | { |
| 389 | throw new Pluf_Exception_NotImplemented(); |
| 390 | } |
| 391 | |
| 392 | /** |
| 393 | * Sync the changes in the repository with the timeline. |
| 394 | * |
| 395 | */ |
| 396 | public static function syncTimeline($project, $force=false) |
| 397 | { |
| 398 | $cache = Pluf_Cache::factory(); |
| 399 | $key = 'IDF_Scm:'.$project->shortname.':lastsync'; |
| 400 | if ($force or null === ($res=$cache->get($key))) { |
| 401 | $scm = IDF_Scm::get($project); |
| 402 | if ($scm->isAvailable()) { |
| 403 | foreach ($scm->getChangeLog($scm->getMainBranch(), 25) as $change) { |
| 404 | IDF_Commit::getOrAdd($change, $project); |
| 405 | } |
| 406 | $cache->set($key, true, (int)(Pluf::f('cache_timeout', 300)/2)); |
| 407 | } |
| 408 | } |
| 409 | } |
| 410 | |
| 411 | /** |
| 412 | * Given a path, encode everything but the / |
| 413 | */ |
| 414 | public static function smartEncode($path) |
| 415 | { |
| 416 | return str_replace('%2F', '/', rawurlencode($path)); |
| 417 | } |
| 418 | } |
| 419 | |
| 420 | |
