PageRenderTime 45ms CodeModel.GetById 20ms RepoModel.GetById 1ms app.codeStats 0ms

/wwwroot/phpbb/phpbb/event/php_exporter.php

https://github.com/spring/spring-website
PHP | 718 lines | 451 code | 76 blank | 191 comment | 68 complexity | e3ce642501539ac8198775816d5ce9b9 MD5 | raw file
Possible License(s): GPL-2.0, LGPL-2.1, Apache-2.0, LGPL-3.0, BSD-3-Clause
  1. <?php
  2. /**
  3. *
  4. * This file is part of the phpBB Forum Software package.
  5. *
  6. * @copyright (c) phpBB Limited <https://www.phpbb.com>
  7. * @license GNU General Public License, version 2 (GPL-2.0)
  8. *
  9. * For full copyright and license information, please see
  10. * the docs/CREDITS.txt file.
  11. *
  12. */
  13. namespace phpbb\event;
  14. /**
  15. * Class php_exporter
  16. * Crawls through a list of files and grabs all php-events
  17. */
  18. class php_exporter
  19. {
  20. /** @var string Path where we look for files*/
  21. protected $path;
  22. /** @var string phpBB Root Path */
  23. protected $root_path;
  24. /** @var string The minimum version for the events to return */
  25. protected $min_version;
  26. /** @var string The maximum version for the events to return */
  27. protected $max_version;
  28. /** @var string */
  29. protected $current_file;
  30. /** @var string */
  31. protected $current_event;
  32. /** @var int */
  33. protected $current_event_line;
  34. /** @var array */
  35. protected $events;
  36. /** @var array */
  37. protected $file_lines;
  38. /**
  39. * @param string $phpbb_root_path
  40. * @param mixed $extension String 'vendor/ext' to filter, null for phpBB core
  41. * @param string $min_version
  42. * @param string $max_version
  43. */
  44. public function __construct($phpbb_root_path, $extension = null, $min_version = null, $max_version = null)
  45. {
  46. $this->root_path = $phpbb_root_path;
  47. $this->path = $phpbb_root_path;
  48. $this->events = $this->file_lines = array();
  49. $this->current_file = $this->current_event = '';
  50. $this->current_event_line = 0;
  51. $this->min_version = $min_version;
  52. $this->max_version = $max_version;
  53. $this->path = $this->root_path;
  54. if ($extension)
  55. {
  56. $this->path .= 'ext/' . $extension . '/';
  57. }
  58. }
  59. /**
  60. * Get the list of all events
  61. *
  62. * @return array Array with events: name => details
  63. */
  64. public function get_events()
  65. {
  66. return $this->events;
  67. }
  68. /**
  69. * Set current event data
  70. *
  71. * @param string $name Name of the current event (used for error messages)
  72. * @param int $line Line where the current event is placed in
  73. * @return null
  74. */
  75. public function set_current_event($name, $line)
  76. {
  77. $this->current_event = $name;
  78. $this->current_event_line = $line;
  79. }
  80. /**
  81. * Set the content of this file
  82. *
  83. * @param array $content Array with the lines of the file
  84. * @return null
  85. */
  86. public function set_content($content)
  87. {
  88. $this->file_lines = $content;
  89. }
  90. /**
  91. * Crawl the phpBB/ directory for php events
  92. * @return int The number of events found
  93. */
  94. public function crawl_phpbb_directory_php()
  95. {
  96. $files = $this->get_recursive_file_list();
  97. $this->events = array();
  98. foreach ($files as $file)
  99. {
  100. $this->crawl_php_file($file);
  101. }
  102. ksort($this->events);
  103. return sizeof($this->events);
  104. }
  105. /**
  106. * Returns a list of files in $dir
  107. *
  108. * @return array List of files (including the path)
  109. */
  110. public function get_recursive_file_list()
  111. {
  112. try
  113. {
  114. $iterator = new \RecursiveIteratorIterator(
  115. new \phpbb\event\recursive_event_filter_iterator(
  116. new \RecursiveDirectoryIterator(
  117. $this->path,
  118. \FilesystemIterator::SKIP_DOTS
  119. ),
  120. $this->path
  121. ),
  122. \RecursiveIteratorIterator::LEAVES_ONLY
  123. );
  124. }
  125. catch (\Exception $e)
  126. {
  127. return array();
  128. }
  129. $files = array();
  130. foreach ($iterator as $file_info)
  131. {
  132. /** @var \RecursiveDirectoryIterator $file_info */
  133. $relative_path = $iterator->getInnerIterator()->getSubPathname();
  134. $files[] = str_replace(DIRECTORY_SEPARATOR, '/', $relative_path);
  135. }
  136. return $files;
  137. }
  138. /**
  139. * Format the php events as a wiki table
  140. *
  141. * @param string $action
  142. * @return string
  143. */
  144. public function export_events_for_wiki($action = '')
  145. {
  146. if ($action === 'diff')
  147. {
  148. $wiki_page = '=== PHP Events (Hook Locations) ===' . "\n";
  149. }
  150. else
  151. {
  152. $wiki_page = '= PHP Events (Hook Locations) =' . "\n";
  153. }
  154. $wiki_page .= '{| class="sortable zebra" cellspacing="0" cellpadding="5"' . "\n";
  155. $wiki_page .= '! Identifier !! Placement !! Arguments !! Added in Release !! Explanation' . "\n";
  156. foreach ($this->events as $event)
  157. {
  158. $wiki_page .= '|- id="' . $event['event'] . '"' . "\n";
  159. $wiki_page .= '| [[#' . $event['event'] . '|' . $event['event'] . ']] || ' . $event['file'] . ' || ' . implode(', ', $event['arguments']) . ' || ' . $event['since'] . ' || ' . $event['description'] . "\n";
  160. }
  161. $wiki_page .= '|}' . "\n";
  162. return $wiki_page;
  163. }
  164. /**
  165. * @param string $file
  166. * @return int Number of events found in this file
  167. * @throws \LogicException
  168. */
  169. public function crawl_php_file($file)
  170. {
  171. $this->current_file = $file;
  172. $this->file_lines = array();
  173. $content = file_get_contents($this->path . $this->current_file);
  174. $num_events_found = 0;
  175. if (strpos($content, "dispatcher->trigger_event('") || strpos($content, "dispatcher->dispatch('"))
  176. {
  177. $this->set_content(explode("\n", $content));
  178. for ($i = 0, $num_lines = sizeof($this->file_lines); $i < $num_lines; $i++)
  179. {
  180. $event_line = false;
  181. $found_trigger_event = strpos($this->file_lines[$i], "dispatcher->trigger_event('");
  182. $arguments = array();
  183. if ($found_trigger_event !== false)
  184. {
  185. $event_line = $i;
  186. $this->set_current_event($this->get_event_name($event_line, false), $event_line);
  187. // Find variables of the event
  188. $arguments = $this->get_vars_from_array();
  189. $doc_vars = $this->get_vars_from_docblock();
  190. $this->validate_vars_docblock_array($arguments, $doc_vars);
  191. }
  192. else
  193. {
  194. $found_dispatch = strpos($this->file_lines[$i], "dispatcher->dispatch('");
  195. if ($found_dispatch !== false)
  196. {
  197. $event_line = $i;
  198. $this->set_current_event($this->get_event_name($event_line, true), $event_line);
  199. }
  200. }
  201. if ($event_line)
  202. {
  203. // Validate @event
  204. $event_line_num = $this->find_event();
  205. $this->validate_event($this->current_event, $this->file_lines[$event_line_num]);
  206. // Validate @since
  207. $since_line_num = $this->find_since();
  208. $since = $this->validate_since($this->file_lines[$since_line_num]);
  209. $changed_line_nums = $this->find_changed('changed');
  210. if (empty($changed_line_nums))
  211. {
  212. $changed_line_nums = $this->find_changed('change');
  213. }
  214. $changed_versions = array();
  215. if (!empty($changed_line_nums))
  216. {
  217. foreach ($changed_line_nums as $changed_line_num)
  218. {
  219. $changed_versions[] = $this->validate_changed($this->file_lines[$changed_line_num]);
  220. }
  221. }
  222. if (!$this->version_is_filtered($since))
  223. {
  224. $valid_version = false;
  225. foreach ($changed_versions as $changed)
  226. {
  227. $valid_version = $valid_version || $this->version_is_filtered($changed);
  228. }
  229. if (!$valid_version)
  230. {
  231. continue;
  232. }
  233. }
  234. // Find event description line
  235. $description_line_num = $this->find_description();
  236. $description = substr(trim($this->file_lines[$description_line_num]), strlen('* '));
  237. if (isset($this->events[$this->current_event]))
  238. {
  239. throw new \LogicException("The event '{$this->current_event}' from file "
  240. . "'{$this->current_file}:{$event_line_num}' already exists in file "
  241. . "'{$this->events[$this->current_event]['file']}'", 10);
  242. }
  243. sort($arguments);
  244. $this->events[$this->current_event] = array(
  245. 'event' => $this->current_event,
  246. 'file' => $this->current_file,
  247. 'arguments' => $arguments,
  248. 'since' => $since,
  249. 'description' => $description,
  250. );
  251. $num_events_found++;
  252. }
  253. }
  254. }
  255. return $num_events_found;
  256. }
  257. /**
  258. * The version to check
  259. *
  260. * @param string $version
  261. * @return bool
  262. */
  263. protected function version_is_filtered($version)
  264. {
  265. return (!$this->min_version || phpbb_version_compare($this->min_version, $version, '<='))
  266. && (!$this->max_version || phpbb_version_compare($this->max_version, $version, '>='));
  267. }
  268. /**
  269. * Find the name of the event inside the dispatch() line
  270. *
  271. * @param int $event_line
  272. * @param bool $is_dispatch Do we look for dispatch() or trigger_event() ?
  273. * @return string Name of the event
  274. * @throws \LogicException
  275. */
  276. public function get_event_name($event_line, $is_dispatch)
  277. {
  278. $event_text_line = $this->file_lines[$event_line];
  279. $event_text_line = ltrim($event_text_line, "\t ");
  280. if ($is_dispatch)
  281. {
  282. $regex = '#\$([a-z](?:[a-z0-9_]|->)*)';
  283. $regex .= '->dispatch\(';
  284. $regex .= '\'' . $this->preg_match_event_name() . '\'';
  285. $regex .= '\);#';
  286. }
  287. else
  288. {
  289. $regex = '#extract\(\$([a-z](?:[a-z0-9_]|->)*)';
  290. $regex .= '->trigger_event\(';
  291. $regex .= '\'' . $this->preg_match_event_name() . '\'';
  292. $regex .= ', compact\(\$vars\)\)\);#';
  293. }
  294. $match = array();
  295. preg_match($regex, $event_text_line, $match);
  296. if (!isset($match[2]))
  297. {
  298. throw new \LogicException("Can not find event name in line '{$event_text_line}' "
  299. . "in file '{$this->current_file}:{$event_line}'", 1);
  300. }
  301. return $match[2];
  302. }
  303. /**
  304. * Returns a regex match for the event name
  305. *
  306. * @return string
  307. */
  308. protected function preg_match_event_name()
  309. {
  310. return '([a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+)';
  311. }
  312. /**
  313. * Find the $vars array
  314. *
  315. * @return array List of variables
  316. * @throws \LogicException
  317. */
  318. public function get_vars_from_array()
  319. {
  320. $line = ltrim($this->file_lines[$this->current_event_line - 1], "\t");
  321. if ($line === ');')
  322. {
  323. $vars_array = $this->get_vars_from_multi_line_array();
  324. }
  325. else
  326. {
  327. $vars_array = $this->get_vars_from_single_line_array($line);
  328. }
  329. foreach ($vars_array as $var)
  330. {
  331. if (!preg_match('#^([a-zA-Z_][a-zA-Z0-9_]*)$#', $var))
  332. {
  333. throw new \LogicException("Found invalid var '{$var}' in array for event '{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 3);
  334. }
  335. }
  336. sort($vars_array);
  337. return $vars_array;
  338. }
  339. /**
  340. * Find the variables in single line array
  341. *
  342. * @param string $line
  343. * @param bool $throw_multiline Throw an exception when there are too
  344. * many arguments in one line.
  345. * @return array List of variables
  346. * @throws \LogicException
  347. */
  348. public function get_vars_from_single_line_array($line, $throw_multiline = true)
  349. {
  350. $match = array();
  351. preg_match('#^\$vars = array\(\'([a-zA-Z0-9_\' ,]+)\'\);$#', $line, $match);
  352. if (isset($match[1]))
  353. {
  354. $vars_array = explode("', '", $match[1]);
  355. if ($throw_multiline && sizeof($vars_array) > 6)
  356. {
  357. throw new \LogicException('Should use multiple lines for $vars definition '
  358. . "for event '{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 2);
  359. }
  360. return $vars_array;
  361. }
  362. else
  363. {
  364. throw new \LogicException("Can not find '\$vars = array();'-line for event '{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 1);
  365. }
  366. }
  367. /**
  368. * Find the variables in single line array
  369. *
  370. * @return array List of variables
  371. * @throws \LogicException
  372. */
  373. public function get_vars_from_multi_line_array()
  374. {
  375. $current_vars_line = 2;
  376. $var_lines = array();
  377. while (ltrim($this->file_lines[$this->current_event_line - $current_vars_line], "\t") !== '$vars = array(')
  378. {
  379. $var_lines[] = substr(trim($this->file_lines[$this->current_event_line - $current_vars_line]), 0, -1);
  380. $current_vars_line++;
  381. if ($current_vars_line > $this->current_event_line)
  382. {
  383. // Reached the start of the file
  384. throw new \LogicException("Can not find end of \$vars array for event '{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 2);
  385. }
  386. }
  387. return $this->get_vars_from_single_line_array('$vars = array(' . implode(", ", $var_lines) . ');', false);
  388. }
  389. /**
  390. * Find the $vars array
  391. *
  392. * @return array List of variables
  393. * @throws \LogicException
  394. */
  395. public function get_vars_from_docblock()
  396. {
  397. $doc_vars = array();
  398. $current_doc_line = 1;
  399. $found_comment_end = false;
  400. while (ltrim($this->file_lines[$this->current_event_line - $current_doc_line], "\t") !== '/**')
  401. {
  402. if (ltrim($this->file_lines[$this->current_event_line - $current_doc_line], "\t ") === '*/')
  403. {
  404. $found_comment_end = true;
  405. }
  406. if ($found_comment_end)
  407. {
  408. $var_line = trim($this->file_lines[$this->current_event_line - $current_doc_line]);
  409. $var_line = preg_replace('!\s+!', ' ', $var_line);
  410. if (strpos($var_line, '* @var ') === 0)
  411. {
  412. $doc_line = explode(' ', $var_line, 5);
  413. if (sizeof($doc_line) !== 5)
  414. {
  415. throw new \LogicException("Found invalid line '{$this->file_lines[$this->current_event_line - $current_doc_line]}' "
  416. . "for event '{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 1);
  417. }
  418. $doc_vars[] = $doc_line[3];
  419. }
  420. }
  421. $current_doc_line++;
  422. if ($current_doc_line > $this->current_event_line)
  423. {
  424. // Reached the start of the file
  425. throw new \LogicException("Can not find end of docblock for event '{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 2);
  426. }
  427. }
  428. if (empty($doc_vars))
  429. {
  430. // Reached the start of the file
  431. throw new \LogicException("Can not find @var lines for event '{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 3);
  432. }
  433. foreach ($doc_vars as $var)
  434. {
  435. if (!preg_match('#^([a-zA-Z_][a-zA-Z0-9_]*)$#', $var))
  436. {
  437. throw new \LogicException("Found invalid @var '{$var}' in docblock for event "
  438. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 4);
  439. }
  440. }
  441. sort($doc_vars);
  442. return $doc_vars;
  443. }
  444. /**
  445. * Find the "@since" Information line
  446. *
  447. * @return int Absolute line number
  448. * @throws \LogicException
  449. */
  450. public function find_since()
  451. {
  452. return $this->find_tag('since', array('event', 'var'));
  453. }
  454. /**
  455. * Find the "@changed" Information lines
  456. *
  457. * @param string $tag_name Should be 'changed' or 'change'
  458. * @return array Absolute line numbers
  459. * @throws \LogicException
  460. */
  461. public function find_changed($tag_name)
  462. {
  463. $lines = array();
  464. $last_line = 0;
  465. try
  466. {
  467. while ($line = $this->find_tag($tag_name, array('since'), $last_line))
  468. {
  469. $lines[] = $line;
  470. $last_line = $line;
  471. }
  472. }
  473. catch (\LogicException $e)
  474. {
  475. // Not changed? No problem!
  476. }
  477. return $lines;
  478. }
  479. /**
  480. * Find the "@event" Information line
  481. *
  482. * @return int Absolute line number
  483. */
  484. public function find_event()
  485. {
  486. return $this->find_tag('event', array());
  487. }
  488. /**
  489. * Find a "@*" Information line
  490. *
  491. * @param string $find_tag Name of the tag we are trying to find
  492. * @param array $disallowed_tags List of tags that must not appear between
  493. * the tag and the actual event
  494. * @param int $skip_to_line Skip lines until this one
  495. * @return int Absolute line number
  496. * @throws \LogicException
  497. */
  498. public function find_tag($find_tag, $disallowed_tags, $skip_to_line = 0)
  499. {
  500. $find_tag_line = $skip_to_line ? $this->current_event_line - $skip_to_line + 1 : 0;
  501. $found_comment_end = ($skip_to_line) ? true : false;
  502. while (strpos(ltrim($this->file_lines[$this->current_event_line - $find_tag_line], "\t "), '* @' . $find_tag . ' ') !== 0)
  503. {
  504. if ($found_comment_end && ltrim($this->file_lines[$this->current_event_line - $find_tag_line], "\t") === '/**')
  505. {
  506. // Reached the start of this doc block
  507. throw new \LogicException("Can not find '@{$find_tag}' information for event "
  508. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 1);
  509. }
  510. foreach ($disallowed_tags as $disallowed_tag)
  511. {
  512. if ($found_comment_end && strpos(ltrim($this->file_lines[$this->current_event_line - $find_tag_line], "\t "), '* @' . $disallowed_tag) === 0)
  513. {
  514. // Found @var after the @since
  515. throw new \LogicException("Found '@{$disallowed_tag}' information after '@{$find_tag}' for event "
  516. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 3);
  517. }
  518. }
  519. if (ltrim($this->file_lines[$this->current_event_line - $find_tag_line], "\t ") === '*/')
  520. {
  521. $found_comment_end = true;
  522. }
  523. $find_tag_line++;
  524. if ($find_tag_line >= $this->current_event_line)
  525. {
  526. // Reached the start of the file
  527. throw new \LogicException("Can not find '@{$find_tag}' information for event "
  528. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 2);
  529. }
  530. }
  531. return $this->current_event_line - $find_tag_line;
  532. }
  533. /**
  534. * Find a "@*" Information line
  535. *
  536. * @return int Absolute line number
  537. * @throws \LogicException
  538. */
  539. public function find_description()
  540. {
  541. $find_desc_line = 0;
  542. while (ltrim($this->file_lines[$this->current_event_line - $find_desc_line], "\t") !== '/**')
  543. {
  544. $find_desc_line++;
  545. if ($find_desc_line > $this->current_event_line)
  546. {
  547. // Reached the start of the file
  548. throw new \LogicException("Can not find a description for event "
  549. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 1);
  550. }
  551. }
  552. $find_desc_line = $this->current_event_line - $find_desc_line + 1;
  553. $desc = trim($this->file_lines[$find_desc_line]);
  554. if (strpos($desc, '* @') === 0 || $desc[0] !== '*' || substr($desc, 1) == '')
  555. {
  556. // First line of the doc block is a @-line, empty or only contains "*"
  557. throw new \LogicException("Can not find a description for event "
  558. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 2);
  559. }
  560. return $find_desc_line;
  561. }
  562. /**
  563. * Validate "@since" Information
  564. *
  565. * @param string $line
  566. * @return string
  567. * @throws \LogicException
  568. */
  569. public function validate_since($line)
  570. {
  571. $match = array();
  572. preg_match('#^\* @since (\d+\.\d+\.\d+(?:-(?:a|b|RC|pl)\d+)?)$#', ltrim($line, "\t "), $match);
  573. if (!isset($match[1]))
  574. {
  575. throw new \LogicException("Invalid '@since' information for event "
  576. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'");
  577. }
  578. return $match[1];
  579. }
  580. /**
  581. * Validate "@changed" Information
  582. *
  583. * @param string $line
  584. * @return string
  585. * @throws \LogicException
  586. */
  587. public function validate_changed($line)
  588. {
  589. $match = array();
  590. $line = str_replace("\t", ' ', ltrim($line, "\t "));
  591. preg_match('#^\* @change(d)? (\d+\.\d+\.\d+(?:-(?:a|b|RC|pl)\d+)?)( (?:.*))?$#', $line, $match);
  592. if (!isset($match[2]))
  593. {
  594. throw new \LogicException("Invalid '@changed' information for event "
  595. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'");
  596. }
  597. return $match[2];
  598. }
  599. /**
  600. * Validate "@event" Information
  601. *
  602. * @param string $event_name
  603. * @param string $line
  604. * @return string
  605. * @throws \LogicException
  606. */
  607. public function validate_event($event_name, $line)
  608. {
  609. $event = substr(ltrim($line, "\t "), strlen('* @event '));
  610. if ($event !== trim($event))
  611. {
  612. throw new \LogicException("Invalid '@event' information for event "
  613. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 1);
  614. }
  615. if ($event !== $event_name)
  616. {
  617. throw new \LogicException("Event name does not match '@event' tag for event "
  618. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'", 2);
  619. }
  620. return $event;
  621. }
  622. /**
  623. * Validates that two arrays contain the same strings
  624. *
  625. * @param array $vars_array Variables found in the array line
  626. * @param array $vars_docblock Variables found in the doc block
  627. * @return null
  628. * @throws \LogicException
  629. */
  630. public function validate_vars_docblock_array($vars_array, $vars_docblock)
  631. {
  632. $vars_array = array_unique($vars_array);
  633. $vars_docblock = array_unique($vars_docblock);
  634. $sizeof_vars_array = sizeof($vars_array);
  635. if ($sizeof_vars_array !== sizeof($vars_docblock) || $sizeof_vars_array !== sizeof(array_intersect($vars_array, $vars_docblock)))
  636. {
  637. throw new \LogicException("\$vars array does not match the list of '@var' tags for event "
  638. . "'{$this->current_event}' in file '{$this->current_file}:{$this->current_event_line}'");
  639. }
  640. }
  641. }