Skip to content

Commit

Permalink
Merge pull request #663 from GrahamCampbell/patch-1
Browse files Browse the repository at this point in the history 
PHPDoc fixes
  • Loading branch information
@denis-sokolov
denis-sokolov committed Apr 28, 2020
2 parents 91b85b4 + ad70a86 commit 1fd7ccb
Showing 1 changed file with 112 additions and 67 deletions.
179 changes: 112 additions & 67 deletions src/Whoops/Handler/PrettyPageHandler.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,9 @@ class PrettyPageHandler extends Handler
const EDITOR_XDEBUG = "xdebug";

/**
* Search paths to be scanned for resources, in the reverse
* order they're declared.
* Search paths to be scanned for resources.
*
* Stored in the reverse order they're declared.
*
* @var array
*/
Expand Down Expand Up @@ -84,19 +85,22 @@ class PrettyPageHandler extends Handler
];

/**
* A string identifier for a known IDE/text editor, or a closure
* that resolves a string that can be used to open a given file
* in an editor. If the string contains the special substrings
* %file or %line, they will be replaced with the correct data.
* An identifier for a known IDE/text editor.
*
* Either a string, or a calalble that resolves a string, that can be used
* to open a given file in an editor. If the string contains the special
* substrings %file or %line, they will be replaced with the correct data.
*
* @example
* "txmt://open?url=%file&line=%line"
* @var mixed $editor
* "txmt://open?url=%file&line=%line"
*
* @var callable|string $editor
*/
protected $editor;

/**
* A list of known editor strings
* A list of known editor strings.
*
* @var array
*/
protected $editors = [
Expand All @@ -118,6 +122,8 @@ class PrettyPageHandler extends Handler

/**
* Constructor.
*
* @return void
*/
public function __construct()
{
Expand Down Expand Up @@ -271,9 +277,9 @@ public function handle()
}

/**
* Get the stack trace frames of the exception that is currently being handled.
* Get the stack trace frames of the exception currently being handled.
*
* @return \Whoops\Exception\FrameCollection;
* @return \Whoops\Exception\FrameCollection
*/
protected function getExceptionFrames()
{
Expand All @@ -294,7 +300,7 @@ protected function getExceptionFrames()
}

/**
* Get the code of the exception that is currently being handled.
* Get the code of the exception currently being handled.
*
* @return string
*/
Expand All @@ -321,10 +327,14 @@ public function contentType()

/**
* Adds an entry to the list of tables displayed in the template.
*
* The expected data is a simple associative array. Any nested arrays
* will be flattened with print_r
* will be flattened with `print_r`.
*
* @param string $label
* @param array $data
*
* @return void
*/
public function addDataTable($label, array $data)
{
Expand All @@ -333,13 +343,17 @@ public function addDataTable($label, array $data)

/**
* Lazily adds an entry to the list of tables displayed in the table.
* The supplied callback argument will be called when the error is rendered,
* it should produce a simple associative array. Any nested arrays will
* be flattened with print_r.
*
* The supplied callback argument will be called when the error is
* rendered, it should produce a simple associative array. Any nested
* arrays will be flattened with `print_r`.
*
* @param string $label
* @param callable $callback Callable returning an associative array
*
* @throws InvalidArgumentException If $callback is not callable
* @param string $label
* @param callable $callback Callable returning an associative array
*
* @return void
*/
public function addDataTableCallback($label, /* callable */ $callback)
{
Expand All @@ -362,9 +376,12 @@ public function addDataTableCallback($label, /* callable */ $callback)

/**
* Returns all the extra data tables registered with this handler.
* Optionally accepts a 'label' parameter, to only return the data
* table under that label.
* @param string|null $label
*
* Optionally accepts a 'label' parameter, to only return the data table
* under that label.
*
* @param string|null $label
*
* @return array[]|callable
*/
public function getDataTables($label = null)
Expand All @@ -378,10 +395,14 @@ public function getDataTables($label = null)
}

/**
* Allows to disable all attempts to dynamically decide whether to
* handle or return prematurely.
* Set this to ensure that the handler will perform no matter what.
* @param bool|null $value
* Set whether to handle unconditionally.
*
* Allows to disable all attempts to dynamically decide whether to handle
* or return prematurely. Set this to ensure that the handler will perform,
* no matter what.
*
* @param bool|null $value
*
* @return bool|null
*/
public function handleUnconditionally($value = null)
Expand All @@ -394,10 +415,11 @@ public function handleUnconditionally($value = null)
}

/**
* Adds an editor resolver, identified by a string
* name, and that may be a string path, or a callable
* resolver. If the callable returns a string, it will
* be set as the file reference's href attribute.
* Adds an editor resolver.
*
* Either a string, or a closure that resolves a string, that can be used
* to open a given file in an editor. If the string contains the special
* substrings %file or %line, they will be replaced with the correct data.
*
* @example
* $run->addEditor('macvim', "mvim://open?url=file://%file&line=%line")
Expand All @@ -406,27 +428,33 @@ public function handleUnconditionally($value = null)
* unlink($file);
* return "http://stackoverflow.com";
* });
* @param string $identifier
*
* @param string $identifier
* @param string|callable $resolver
*
* @return void
*/
public function addEditor($identifier, $resolver)
{
$this->editors[$identifier] = $resolver;
}

/**
* Set the editor to use to open referenced files, by a string
* identifier, or a callable that will be executed for every
* file reference, with a $file and $line argument, and should
* return a string.
* Set the editor to use to open referenced files.
*
* Pass either the name of a configured editor, or a closure that directly
* resolves an editor string.
*
* @example
* $run->setEditor(function($file, $line) { return "file:///{$file}"; });
* @example
* $run->setEditor('sublime');
*
* @param string|callable $editor
*
* @throws InvalidArgumentException If invalid argument identifier provided
* @param string|callable $editor
*
* @return void
*/
public function setEditor($editor)
{
Expand All @@ -441,14 +469,13 @@ public function setEditor($editor)
}

/**
* Given a string file path, and an integer file line,
* executes the editor resolver and returns, if available,
* a string that may be used as the href property for that
* file reference.
* Get the editor href for a given file and line, if available.
*
* @param string $filePath
* @param int $line
*
* @throws InvalidArgumentException If editor resolver does not return a string
* @param string $filePath
* @param int $line
*
* @return string|bool
*/
public function getEditorHref($filePath, $line)
Expand All @@ -474,13 +501,13 @@ public function getEditorHref($filePath, $line)
}

/**
* Given a boolean if the editor link should
* act as an Ajax request. The editor must be a
* valid callable function/closure
* Determine if the editor link should act as an Ajax request.
*
* @param string $filePath
* @param int $line
*
* @throws UnexpectedValueException If editor resolver does not return a boolean
*
* @throws UnexpectedValueException If editor resolver does not return a boolean
* @param string $filePath
* @param int $line
* @return bool
*/
public function getEditorAjax($filePath, $line)
Expand All @@ -497,12 +524,11 @@ public function getEditorAjax($filePath, $line)
}

/**
* Given a boolean if the editor link should
* act as an Ajax request. The editor must be a
* valid callable function/closure
* Determines both the editor and if ajax should be used.
*
* @param string $filePath
* @param int $line
*
* @param string $filePath
* @param int $line
* @return array
*/
protected function getEditor($filePath, $line)
Expand Down Expand Up @@ -546,7 +572,10 @@ protected function getEditor($filePath, $line)
}

/**
* @param string $title
* Set the page title.
*
* @param string $title
*
* @return void
*/
public function setPageTitle($title)
Expand All @@ -555,6 +584,8 @@ public function setPageTitle($title)
}

/**
* Get the page title.
*
* @return string
*/
public function getPageTitle()
Expand All @@ -563,12 +594,12 @@ public function getPageTitle()
}

/**
* Adds a path to the list of paths to be searched for
* resources.
* Adds a path to the list of paths to be searched for resources.
*
* @param string $path
*
* @throws InvalidArgumentException If $path is not a valid directory
*
* @param string $path
* @return void
*/
public function addResourcePath($path)
Expand All @@ -585,7 +616,8 @@ public function addResourcePath($path)
/**
* Adds a custom css file to be loaded.
*
* @param string $name
* @param string $name
*
* @return void
*/
public function addCustomCss($name)
Expand All @@ -603,13 +635,15 @@ public function getResourcePaths()

/**
* Finds a resource, by its relative path, in all available search paths.
*
* The search is performed starting at the last search path, and all the
* way back to the first, enabling a cascading-type system of overrides
* for all resources.
* way back to the first, enabling a cascading-type system of overrides for
* all resources.
*
* @param string $resource
*
* @throws RuntimeException If resource cannot be found in any of the available paths
*
* @param string $resource
* @return string
*/
protected function getResource($resource)
Expand Down Expand Up @@ -655,7 +689,8 @@ public function getResourcesPath()
/**
* @deprecated
*
* @param string $resourcesPath
* @param string $resourcesPath
*
* @return void
*/
public function setResourcesPath($resourcesPath)
Expand All @@ -677,6 +712,8 @@ public function getApplicationPaths()
* Set the application paths.
*
* @param array $applicationPaths
*
* @return void
*/
public function setApplicationPaths($applicationPaths)
{
Expand All @@ -687,6 +724,8 @@ public function setApplicationPaths($applicationPaths)
* Set the application root path.
*
* @param string $applicationRootPath
*
* @return void
*/
public function setApplicationRootPath($applicationRootPath)
{
Expand All @@ -696,8 +735,10 @@ public function setApplicationRootPath($applicationRootPath)
/**
* blacklist a sensitive value within one of the superglobal arrays.
*
* @param $superGlobalName string the name of the superglobal array, e.g. '_GET'
* @param $key string the key within the superglobal
* @param string $superGlobalName The name of the superglobal array, e.g. '_GET'
* @param string $key The key within the superglobal
*
* @return void
*/
public function blacklist($superGlobalName, $key)
{
Expand All @@ -706,24 +747,28 @@ public function blacklist($superGlobalName, $key)

/**
* Checks all values within the given superGlobal array.
* Blacklisted values will be replaced by a equal length string cointaining only '*' characters.
*
* We intentionally dont rely on $GLOBALS as it depends on 'auto_globals_jit' php.ini setting.
* Blacklisted values will be replaced by a equal length string cointaining
* only '*' characters. We intentionally dont rely on $GLOBALS as it
* depends on the 'auto_globals_jit' php.ini setting.
*
* @param array $superGlobal One of the superglobal arrays
* @param string $superGlobalName The name of the superglobal array, e.g. '_GET'
*
* @param $superGlobal array One of the superglobal arrays
* @param $superGlobalName string the name of the superglobal array, e.g. '_GET'
* @return array $values without sensitive data
*/
private function masked(array $superGlobal, $superGlobalName)
{
$blacklisted = $this->blacklist[$superGlobalName];

$values = $superGlobal;

foreach ($blacklisted as $key) {
if (isset($superGlobal[$key]) && is_string($superGlobal[$key])) {
$values[$key] = str_repeat('*', strlen($superGlobal[$key]));
}
}

return $values;
}
}

0 comments on commit 1fd7ccb

Please sign in to comment.