[ Index ]

PHP Cross Reference of BuddyPress

title

Body

[close]

/src/bp-core/classes/ -> class-bp-attachment.php (source)

   1  <?php
   2  /**
   3   * Core attachment class.
   4   *
   5   * @package BuddyPress
   6   * @subpackage Core
   7   * @since 2.3.0
   8   */
   9  
  10  // Exit if accessed directly.
  11  defined( 'ABSPATH' ) || exit;
  12  
  13  /**
  14   * BP Attachment class.
  15   *
  16   * Extend it to manage your component's uploads.
  17   *
  18   * @since 2.3.0
  19   */
  20  abstract class BP_Attachment {
  21  
  22      /** Upload properties *****************************************************/
  23  
  24      /**
  25       * The file being uploaded.
  26       *
  27       * @var array
  28       */
  29      public $attachment = array();
  30  
  31      /**
  32       * The default args to be merged with the
  33       * ones passed by the child class.
  34       *
  35       * @var array
  36       */
  37      protected $default_args = array(
  38          'original_max_filesize'  => 0,
  39          'allowed_mime_types'     => array(),
  40          'base_dir'               => '',
  41          'action'                 => '',
  42          'file_input'             => '',
  43          'upload_error_strings'   => array(),
  44          'required_wp_files'      => array( 'file' ),
  45          'upload_dir_filter_args' => 0,
  46      );
  47  
  48      /**
  49       * Construct Upload parameters.
  50       *
  51       * @since 2.3.0
  52       * @since 2.4.0 Add the $upload_dir_filter_args argument to the $arguments array
  53       *
  54       * @param array|string $args {
  55       *     @type int    $original_max_filesize  Maximum file size in kilobytes. Defaults to php.ini settings.
  56       *     @type array  $allowed_mime_types     List of allowed file extensions (eg: array( 'jpg', 'gif', 'png' ) ).
  57       *                                          Defaults to WordPress allowed mime types.
  58       *     @type string $base_dir               Component's upload base directory. Defaults to WordPress 'uploads'.
  59       *     @type string $action                 The upload action used when uploading a file, $_POST['action'] must be set
  60       *                                          and its value must equal $action {@link wp_handle_upload()} (required).
  61       *     @type string $file_input             The name attribute used in the file input. (required).
  62       *     @type array  $upload_error_strings   A list of specific error messages (optional).
  63       *     @type array  $required_wp_files      The list of required WordPress core files. Default: array( 'file' ).
  64       *     @type int    $upload_dir_filter_args 1 to receive the original Upload dir array in the Upload dir filter, 0 otherwise.
  65       *                                          Defaults to 0 (optional).
  66       * }
  67       */
  68  	public function __construct( $args = '' ) {
  69          // Upload action and the file input name are required parameters.
  70          if ( empty( $args['action'] ) || empty( $args['file_input'] ) ) {
  71              return false;
  72          }
  73  
  74          // Sanitize the action ID and the file input name.
  75          $this->action     = sanitize_key( $args['action'] );
  76          $this->file_input = sanitize_key( $args['file_input'] );
  77  
  78          /**
  79           * Max file size defaults to php ini settings or, in the case of
  80           * a multisite config, the root site fileupload_maxk option
  81           */
  82          $this->default_args['original_max_filesize'] = (int) wp_max_upload_size();
  83  
  84          $params = bp_parse_args( $args, $this->default_args, $this->action . '_upload_params' );
  85  
  86          foreach ( $params as $key => $param ) {
  87              if ( 'upload_error_strings' === $key ) {
  88                  $this->{$key} = $this->set_upload_error_strings( $param );
  89  
  90              // Sanitize the base dir.
  91              } elseif ( 'base_dir' === $key ) {
  92                  $this->{$key} = sanitize_title( $param );
  93  
  94              // Sanitize the upload dir filter arg to pass.
  95              } elseif ( 'upload_dir_filter_args' === $key ) {
  96                  $this->{$key} = (int) $param;
  97  
  98              // Action & File input are already set and sanitized.
  99              } elseif ( 'action' !== $key && 'file_input' !== $key ) {
 100                  $this->{$key} = $param;
 101              }
 102          }
 103  
 104          // Set the path/url and base dir for uploads.
 105          $this->set_upload_dir();
 106      }
 107  
 108      /**
 109       * Set upload path and url for the component.
 110       *
 111       * @since 2.3.0
 112       *
 113       */
 114  	public function set_upload_dir() {
 115          // Set the directory, path, & url variables.
 116          $this->upload_dir  = bp_upload_dir();
 117  
 118          if ( empty( $this->upload_dir ) ) {
 119              return false;
 120          }
 121  
 122          $this->upload_path = $this->upload_dir['basedir'];
 123          $this->url         = $this->upload_dir['baseurl'];
 124  
 125          // Ensure URL is https if SSL is set/forced.
 126          if ( is_ssl() ) {
 127              $this->url = str_replace( 'http://', 'https://', $this->url );
 128          }
 129  
 130          /**
 131           * Custom base dir.
 132           *
 133           * If the component set this property, set the specific path, url and create the dir
 134           */
 135          if ( ! empty( $this->base_dir ) ) {
 136              $this->upload_path = trailingslashit( $this->upload_path ) . $this->base_dir;
 137              $this->url         = trailingslashit( $this->url  ) . $this->base_dir;
 138  
 139              // Finally create the base dir.
 140              $this->create_dir();
 141          }
 142      }
 143  
 144      /**
 145       * Set Upload error messages.
 146       *
 147       * Used into the $overrides argument of BP_Attachment->upload()
 148       *
 149       * @since 2.3.0
 150       *
 151       * @param array $param A list of error messages to add to BuddyPress core ones.
 152       * @return array $upload_errors The list of upload errors.
 153       */
 154  	public function set_upload_error_strings( $param = array() ) {
 155          /**
 156           * Index of the array is the error code
 157           * Custom errors will start at 9 code
 158           */
 159          $upload_errors = array(
 160              0 => __( 'The file was uploaded successfully', 'buddypress' ),
 161              1 => __( 'The uploaded file exceeds the maximum allowed file size for this site', 'buddypress' ),
 162              2 => sprintf( __( 'The uploaded file exceeds the maximum allowed file size of: %s', 'buddypress' ), size_format( $this->original_max_filesize ) ),
 163              3 => __( 'The uploaded file was only partially uploaded.', 'buddypress' ),
 164              4 => __( 'No file was uploaded.', 'buddypress' ),
 165              5 => '',
 166              6 => __( 'Missing a temporary folder.', 'buddypress' ),
 167              7 => __( 'Failed to write file to disk.', 'buddypress' ),
 168              8 => __( 'File upload stopped by extension.', 'buddypress' ),
 169          );
 170  
 171          if ( ! array_intersect_key( $upload_errors, (array) $param ) ) {
 172              foreach ( $param as $key_error => $error_message ) {
 173                  $upload_errors[ $key_error ] = $error_message;
 174              }
 175          }
 176  
 177          return $upload_errors;
 178      }
 179  
 180      /**
 181       * Include the WordPress core needed files.
 182       *
 183       * @since 2.3.0
 184       */
 185  	public function includes() {
 186          foreach ( array_unique( $this->required_wp_files ) as $wp_file ) {
 187              if ( ! file_exists( ABSPATH . "/wp-admin/includes/{$wp_file}.php" ) ) {
 188                  continue;
 189              }
 190  
 191              require_once( ABSPATH . "/wp-admin/includes/{$wp_file}.php" );
 192          }
 193      }
 194  
 195      /**
 196       * Upload the attachment.
 197       *
 198       * @since 2.3.0
 199       *
 200       * @param array       $file              The appropriate entry the from $_FILES superglobal.
 201       * @param string      $upload_dir_filter A specific filter to be applied to 'upload_dir' (optional).
 202       * @param string|null $time              Optional. Time formatted in 'yyyy/mm'. Default null.
 203       * @return array On success, returns an associative array of file attributes.
 204       *               On failure, returns an array containing the error message
 205       *               (eg: array( 'error' => $message ) )
 206       */
 207  	public function upload( $file, $upload_dir_filter = '', $time = null ) {
 208          /**
 209           * Upload action and the file input name are required parameters.
 210           *
 211           * @see BP_Attachment:__construct()
 212           */
 213          if ( empty( $this->action ) || empty( $this->file_input ) ) {
 214              return false;
 215          }
 216  
 217          /**
 218           * Add custom rules before enabling the file upload
 219           */
 220          add_filter( "{$this->action}_prefilter", array( $this, 'validate_upload' ), 10, 1 );
 221  
 222          // Set Default overrides.
 223          $overrides = array(
 224              'action'               => $this->action,
 225              'upload_error_strings' => $this->upload_error_strings,
 226          );
 227  
 228          /**
 229           * Add a mime override if needed
 230           * Used to restrict uploads by extensions
 231           */
 232          if ( ! empty( $this->allowed_mime_types ) ) {
 233              $mime_types = $this->validate_mime_types();
 234  
 235              if ( ! empty( $mime_types ) ) {
 236                  $overrides['mimes'] = $mime_types;
 237              }
 238          }
 239  
 240          /**
 241           * If you need to add some overrides we haven't thought of.
 242           *
 243           * @param array $overrides The wp_handle_upload overrides
 244           */
 245          $overrides = apply_filters( 'bp_attachment_upload_overrides', $overrides );
 246  
 247          $this->includes();
 248  
 249          /**
 250           * If the $base_dir was set when constructing the class,
 251           * and no specific filter has been requested, use a default
 252           * filter to create the specific $base dir
 253           * @see  BP_Attachment->upload_dir_filter()
 254           */
 255          if ( empty( $upload_dir_filter ) && ! empty( $this->base_dir ) ) {
 256              $upload_dir_filter = array( $this, 'upload_dir_filter' );
 257          }
 258  
 259          // Make sure the file will be uploaded in the attachment directory.
 260          if ( ! empty( $upload_dir_filter ) ) {
 261              add_filter( 'upload_dir', $upload_dir_filter, 10, $this->upload_dir_filter_args );
 262          }
 263  
 264          // Helper for utf-8 filenames.
 265          add_filter( 'sanitize_file_name', array( $this, 'sanitize_utf8_filename' ) );
 266  
 267          // Upload the attachment.
 268          $this->attachment = wp_handle_upload( $file[ $this->file_input ], $overrides, $time );
 269  
 270          remove_filter( 'sanitize_file_name', array( $this, 'sanitize_utf8_filename' ) );
 271  
 272          // Restore WordPress Uploads data.
 273          if ( ! empty( $upload_dir_filter ) ) {
 274              remove_filter( 'upload_dir', $upload_dir_filter, 10 );
 275          }
 276  
 277          // Finally return the uploaded file or the error.
 278          return $this->attachment;
 279      }
 280  
 281      /**
 282       * Helper to convert utf-8 characters in filenames to their ASCII equivalent.
 283       *
 284       * @since 2.9.0
 285       *
 286       * @param  string $retval Filename.
 287       * @return string
 288       */
 289  	public function sanitize_utf8_filename( $retval ) {
 290          // PHP 5.4+ or with PECL intl 2.0+
 291          if ( function_exists( 'transliterator_transliterate' ) && seems_utf8( $retval ) ) {
 292              $retval = transliterator_transliterate( 'Any-Latin; Latin-ASCII; [\u0080-\u7fff] remove', $retval );
 293  
 294          // Older.
 295          } else {
 296              // Use WP's built-in function to convert accents to their ASCII equivalent.
 297              $retval = remove_accents( $retval );
 298  
 299              // Still here? use iconv().
 300              if ( function_exists( 'iconv' ) && seems_utf8( $retval ) ) {
 301                  $retval = iconv( 'UTF-8', 'ASCII//TRANSLIT//IGNORE', $retval );
 302              }
 303          }
 304  
 305          return $retval;
 306      }
 307  
 308      /**
 309       * Validate the allowed mime types using WordPress allowed mime types.
 310       *
 311       * In case of a multisite, the mime types are already restricted by
 312       * the 'upload_filetypes' setting. BuddyPress will respect this setting.
 313       *
 314       * @see check_upload_mimes()
 315       *
 316       * @since 2.3.0
 317       *
 318       */
 319  	protected function validate_mime_types() {
 320          $wp_mimes = get_allowed_mime_types();
 321          $valid_mimes = array();
 322  
 323          // Set the allowed mimes for the upload.
 324          foreach ( (array) $this->allowed_mime_types as $ext ) {
 325              foreach ( $wp_mimes as $ext_pattern => $mime ) {
 326                  if ( $ext !== '' && strpos( $ext_pattern, $ext ) !== false ) {
 327                      $valid_mimes[$ext_pattern] = $mime;
 328                  }
 329              }
 330          }
 331          return $valid_mimes;
 332      }
 333  
 334      /**
 335       * Specific upload rules.
 336       *
 337       * Override this function from your child class to build your specific rules
 338       * By default, if an original_max_filesize is provided, a check will be done
 339       * on the file size.
 340       *
 341       * @see BP_Attachment_Avatar->validate_upload() for an example of use
 342       *
 343       * @since 2.3.0
 344       *
 345       * @param array $file The temporary file attributes (before it has been moved).
 346       * @return array The file.
 347       */
 348  	public function validate_upload( $file = array() ) {
 349          // Bail if already an error.
 350          if ( ! empty( $file['error'] ) ) {
 351              return $file;
 352          }
 353  
 354          if ( ! empty( $this->original_max_filesize ) && $file['size'] > $this->original_max_filesize ) {
 355              $file['error'] = 2;
 356          }
 357  
 358          // Return the file.
 359          return $file;
 360      }
 361  
 362      /**
 363       * Default filter to save the attachments.
 364       *
 365       * @since 2.3.0
 366       * @since 2.4.0 Add the $upload_dir parameter to the method
 367       *
 368       *       regarding to context
 369       *
 370       * @param array $upload_dir The original Uploads dir.
 371       * @return array The upload directory data.
 372       */
 373  	public function upload_dir_filter( $upload_dir = array() ) {
 374  
 375          /**
 376           * Filters the component's upload directory.
 377           *
 378           * @since 2.3.0
 379           * @since 2.4.0 Include the original Upload directory as the second parameter of the filter.
 380           *
 381           * @param array $value          Array containing the path, URL, and other helpful settings.
 382           * @param array $upload_dir     The original Uploads dir.
 383           */
 384          return apply_filters( 'bp_attachment_upload_dir', array(
 385              'path'    => $this->upload_path,
 386              'url'     => $this->url,
 387              'subdir'  => false,
 388              'basedir' => $this->upload_path,
 389              'baseurl' => $this->url,
 390              'error'   => false
 391          ), $upload_dir );
 392      }
 393  
 394      /**
 395       * Create the custom base directory for the component uploads.
 396       *
 397       * Override this function in your child class to run specific actions.
 398       * (eg: add an .htaccess file)
 399       *
 400       * @since 2.3.0
 401       *
 402       */
 403  	public function create_dir() {
 404          // Bail if no specific base dir is set.
 405          if ( empty( $this->base_dir ) ) {
 406              return false;
 407          }
 408  
 409          // Check if upload path already exists.
 410          if ( ! is_dir( $this->upload_path ) ) {
 411  
 412              // If path does not exist, attempt to create it.
 413              if ( ! wp_mkdir_p( $this->upload_path ) ) {
 414                  return false;
 415              }
 416          }
 417  
 418          // Directory exists.
 419          return true;
 420      }
 421  
 422      /**
 423       * Crop an image file.
 424       *
 425       * @since 2.3.0
 426       *
 427       * @param array $args {
 428       *     @type string $original_file The source file (absolute path) for the Attachment.
 429       *     @type int    $crop_x        The start x position to crop from.
 430       *     @type int    $crop_y        The start y position to crop from.
 431       *     @type int    $crop_w        The width to crop.
 432       *     @type int    $crop_h        The height to crop.
 433       *     @type int    $dst_w         The destination width.
 434       *     @type int    $dst_h         The destination height.
 435       *     @type int    $src_abs       Optional. If the source crop points are absolute.
 436       *     @type string $dst_file      Optional. The destination file to write to.
 437       * }
 438       *
 439       * @return string|WP_Error New filepath on success, WP_Error on failure.
 440       */
 441  	public function crop( $args = array() ) {
 442          $wp_error = new WP_Error();
 443  
 444          $r = bp_parse_args( $args, array(
 445              'original_file' => '',
 446              'crop_x'        => 0,
 447              'crop_y'        => 0,
 448              'crop_w'        => 0,
 449              'crop_h'        => 0,
 450              'dst_w'         => 0,
 451              'dst_h'         => 0,
 452              'src_abs'       => false,
 453              'dst_file'      => false,
 454          ), 'bp_attachment_crop_args' );
 455  
 456          if ( empty( $r['original_file'] ) || ! file_exists( $r['original_file'] ) ) {
 457              $wp_error->add( 'crop_error', __( 'Cropping the file failed: missing source file.', 'buddypress' ) );
 458              return $wp_error;
 459          }
 460  
 461          // Check image file pathes.
 462          $path_error = __( 'Cropping the file failed: the file path is not allowed.', 'buddypress' );
 463  
 464          // Make sure it's coming from an uploaded file.
 465          if ( false === strpos( $r['original_file'], $this->upload_path ) ) {
 466              $wp_error->add( 'crop_error', $path_error );
 467              return $wp_error;
 468          }
 469  
 470          /**
 471           * If no destination file is provided, WordPress will use a default name
 472           * and will write the file in the source file's folder.
 473           * If a destination file is provided, we need to make sure it's going into uploads.
 474           */
 475          if ( ! empty( $r['dst_file'] ) && false === strpos( $r['dst_file'], $this->upload_path ) ) {
 476              $wp_error->add( 'crop_error', $path_error );
 477              return $wp_error;
 478          }
 479  
 480          // Check image file types.
 481          $check_types = array( 'src_file' => array( 'file' => $r['original_file'], 'error' => _x( 'source file', 'Attachment source file', 'buddypress' ) ) );
 482          if ( ! empty( $r['dst_file'] ) ) {
 483              $check_types['dst_file'] = array( 'file' => $r['dst_file'], 'error' => _x( 'destination file', 'Attachment destination file', 'buddypress' ) );
 484          }
 485  
 486          /**
 487           * WordPress image supported types.
 488           * @see wp_attachment_is()
 489           */
 490          $supported_image_types = array(
 491              'jpg'  => 1,
 492              'jpeg' => 1,
 493              'jpe'  => 1,
 494              'gif'  => 1,
 495              'png'  => 1,
 496          );
 497  
 498          foreach ( $check_types as $file ) {
 499              $is_image      = wp_check_filetype( $file['file'] );
 500              $ext           = $is_image['ext'];
 501  
 502              if ( empty( $ext ) || empty( $supported_image_types[ $ext ] ) ) {
 503                  $wp_error->add( 'crop_error', sprintf( __( 'Cropping the file failed: %s is not a supported image file.', 'buddypress' ), $file['error'] ) );
 504                  return $wp_error;
 505              }
 506          }
 507  
 508          // Add the image.php to the required WordPress files, if it's not already the case.
 509          $required_files = array_flip( $this->required_wp_files );
 510          if ( ! isset( $required_files['image'] ) ) {
 511              $this->required_wp_files[] = 'image';
 512          }
 513  
 514          // Load the files.
 515          $this->includes();
 516  
 517          // Finally crop the image.
 518          return wp_crop_image( $r['original_file'], (int) $r['crop_x'], (int) $r['crop_y'], (int) $r['crop_w'], (int) $r['crop_h'], (int) $r['dst_w'], (int) $r['dst_h'], $r['src_abs'], $r['dst_file'] );
 519      }
 520  
 521      /**
 522       * Build script datas for the Uploader UI.
 523       *
 524       * Override this method from your child class to build the script datas.
 525       *
 526       * @since 2.3.0
 527       *
 528       * @return array The javascript localization data.
 529       */
 530  	public function script_data() {
 531          $script_data = array(
 532              'action'            => $this->action,
 533              'file_data_name'    => $this->file_input,
 534              'max_file_size'     => $this->original_max_filesize,
 535              'feedback_messages' => array(
 536                  1 => __( 'Sorry, uploading the file failed.', 'buddypress' ),
 537                  2 => __( 'File successfully uploaded.', 'buddypress' ),
 538              ),
 539          );
 540  
 541          return $script_data;
 542      }
 543  
 544      /**
 545       * Get full data for an image
 546       *
 547       * @since 2.4.0
 548       *
 549       * @param string $file Absolute path to the uploaded image.
 550       * @return bool|array   An associate array containing the width, height and metadatas.
 551       *                      False in case an important image attribute is missing.
 552       */
 553  	public static function get_image_data( $file ) {
 554          // Try to get image basic data.
 555          list( $width, $height, $sourceImageType ) = @getimagesize( $file );
 556  
 557          // No need to carry on if we couldn't get image's basic data.
 558          if ( is_null( $width ) || is_null( $height ) || is_null( $sourceImageType ) ) {
 559              return false;
 560          }
 561  
 562          // Initialize the image data.
 563          $image_data = array(
 564              'width'  => $width,
 565              'height' => $height,
 566          );
 567  
 568          /**
 569           * Make sure the wp_read_image_metadata function is reachable for the old Avatar UI
 570           * or if WordPress < 3.9 (New Avatar UI is not available in this case)
 571           */
 572          if ( ! function_exists( 'wp_read_image_metadata' ) ) {
 573              require_once( ABSPATH . 'wp-admin/includes/image.php' );
 574          }
 575  
 576          // Now try to get image's meta data.
 577          $meta = wp_read_image_metadata( $file );
 578          if ( ! empty( $meta ) ) {
 579              $image_data['meta'] = $meta;
 580          }
 581  
 582          /**
 583           * Filter here to add/remove/edit data to the image full data
 584           *
 585           * @since 2.4.0
 586           *
 587           * @param array $image_data An associate array containing the width, height and metadatas.
 588           */
 589          return apply_filters( 'bp_attachments_get_image_data', $image_data );
 590      }
 591  
 592      /**
 593       * Edit an image file to resize it or rotate it
 594       *
 595       * @since 2.4.0
 596       *
 597       * @param string $attachment_type The attachment type (eg: avatar or cover_image). Required.
 598       * @param array  $args {
 599       *     @type string $file     Absolute path to the image file (required).
 600       *     @type int    $max_w    Max width attribute for the editor's resize method (optional).
 601       *     @type int    $max_h    Max height attribute for the editor's resize method (optional).
 602       *     @type bool   $crop     Crop attribute for the editor's resize method (optional).
 603       *     @type float  $rotate   Angle for the editor's rotate method (optional).
 604       *     @type int    $quality  Compression quality on a 1-100% scale (optional).
 605       *     @type bool   $save     Whether to use the editor's save method or not (optional).
 606       * }
 607       * @return string|WP_Image_Editor|WP_Error The edited image path or the WP_Image_Editor object in case of success,
 608       *                                         an WP_Error object otherwise.
 609       */
 610  	public static function edit_image( $attachment_type, $args = array() ) {
 611          if ( empty( $attachment_type ) ) {
 612              return new WP_Error( 'missing_parameter' );
 613          }
 614  
 615          $r = bp_parse_args( $args, array(
 616              'file'   => '',
 617              'max_w'   => 0,
 618              'max_h'   => 0,
 619              'crop'    => false,
 620              'rotate'  => 0,
 621              'quality' => 90,
 622              'save'    => true,
 623          ), 'attachment_' . $attachment_type . '_edit_image' );
 624  
 625          // Make sure we have to edit the image.
 626          if ( empty( $r['max_w'] ) && empty( $r['max_h'] ) && empty( $r['rotate'] ) && empty( $r['file'] ) ) {
 627              return new WP_Error( 'missing_parameter' );
 628          }
 629  
 630          // Get the image editor.
 631          $editor = wp_get_image_editor( $r['file'] );
 632  
 633          if ( is_wp_error( $editor ) ) {
 634              return $editor;
 635          }
 636  
 637          $editor->set_quality( $r['quality'] );
 638  
 639          if ( ! empty( $r['rotate'] ) ) {
 640              $rotated = $editor->rotate( $r['rotate'] );
 641  
 642              // Stop in case of error.
 643              if ( is_wp_error( $rotated ) ) {
 644                  return $rotated;
 645              }
 646          }
 647  
 648          if ( ! empty( $r['max_w'] ) || ! empty( $r['max_h'] ) ) {
 649              $resized = $editor->resize( $r['max_w'], $r['max_h'], $r['crop'] );
 650  
 651              // Stop in case of error.
 652              if ( is_wp_error( $resized ) ) {
 653                  return $resized;
 654              }
 655          }
 656  
 657          // Use the editor save method to get a path to the edited image.
 658          if ( true === $r['save'] ) {
 659              return $editor->save( $editor->generate_filename() );
 660  
 661          // Need to do some other edit actions or use a specific method to save file.
 662          } else {
 663              return $editor;
 664          }
 665      }
 666  }


Generated: Sat Sep 21 01:01:46 2019 Cross-referenced by PHPXref 0.7.1