sydney/IPB
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Version 5.0.0 beta 1

Browse Source
This commit is contained in:
Neo committed 2025-12-19 16:27:35 -08:00
1 parent 25ddeb65d6
commit 15c7beabc5
6736 files changed
+627902 -497943
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

system/Api/Controller.php
+69 -53
View File
@@ -11,70 +11,86 @@
namespace IPS\Api;
/* To prevent PHP errors (extending class does not exist) revealing path */
if ( !\defined( '\IPS\SUITE_UNIQUE_KEY' ) )
use DirectoryIterator;
use IPS\Application;
use IPS\Http\Url;
use IPS\Member;
use IPS\Output;
use IPS\Settings;
use ReflectionClass;
use ReflectionMethod;
use RuntimeException;
use function count;
use function defined;
use function get_called_class;
use function in_array;
use function method_exists;
if ( !defined( '\IPS\SUITE_UNIQUE_KEY' ) )
{
header( ( isset( $_SERVER['SERVER_PROTOCOL'] ) ? $_SERVER['SERVER_PROTOCOL'] : 'HTTP/1.0' ) . ' 403 Forbidden' );
header( ( $_SERVER['SERVER_PROTOCOL'] ?? 'HTTP/1.0' ) . ' 403 Forbidden' );
exit;
}
/**
* Base API Controller
*/
abstract class _Controller
abstract class Controller
{
/**
* @brief API Key
*/
protected $apiKey;
protected ?Key $apiKey = null;
/**
* @brief OAuth Client
*/
protected $client;
protected ?OAuthClient $client = null;
/**
* @brief OAuth Authenticated Member
*/
protected $member;
protected ?Member $member = null;
/**
* @brief OAuth Scopes
*/
protected $scopes;
protected ?array $scopes = null;
/**
* @brief Used OAuth Scope
*/
protected $usedScope;
protected ?string $usedScope = null;
/**
* @brief Parameters to mask in logs. Keys are the method names and values an array of field or request keys.
*/
public $parametersToMask = array();
public array $parametersToMask = array();
/**
* @brief Name of the method we called
*/
public $methodCalled = NULL;
public ?string $methodCalled = NULL;
/**
* Constructor
*
* @param \IPS\Api\Key $apiKey The API key being used to access, if applicable
* @param Key|null $apiKey The API key being used to access, if applicable
* @param array|null $accessToken Access token for OAuth-authenticated requests
* @return void
*/
public function __construct( \IPS\Api\Key $apiKey = NULL, $accessToken = NULL )
public function __construct( ?Key $apiKey = NULL, ?array $accessToken = NULL )
{
$this->apiKey = $apiKey;
if ( $accessToken )
{
$this->client = \IPS\Api\OAuthClient::load( $accessToken['client_id'] );
$this->client = OAuthClient::load( $accessToken['client_id'] );
$this->scopes = $accessToken['scope'] ? json_decode( $accessToken['scope'] ) : NULL;
if ( $accessToken['member_id'] )
{
$this->member = \IPS\Member::load( $accessToken['member_id'] );
$this->member = Member::load( $accessToken['member_id'] );
}
}
}
@@ -87,7 +103,7 @@ abstract class _Controller
* @param string $method Method
* @return bool
*/
protected function canAccess( $app, $controller, $method )
protected function canAccess( string $app, string $controller, string $method ) : bool
{
if ( $this->apiKey )
{
@@ -111,7 +127,7 @@ abstract class _Controller
* @param string $method Method
* @return bool
*/
protected function shouldLog( $app, $controller, $method )
protected function shouldLog( string $app, string $controller, string $method ) : bool
{
if ( $this->apiKey )
{
@@ -128,47 +144,47 @@ abstract class _Controller
*
* @param array $pathBits The parts to the path called
* @param bool $shouldLog Gets set to TRUE if this call should log
* @return \IPS\Api\Response
* @throws \IPS\Api\Exception
* @return Response
* @throws Exception
*/
public function execute( $pathBits, &$shouldLog )
public function execute( array $pathBits, bool &$shouldLog ) : Response
{
$method = ( isset( $_SERVER['REQUEST_METHOD'] ) and \in_array( mb_strtoupper( $_SERVER['REQUEST_METHOD'] ), array( 'GET', 'POST', 'PUT', 'DELETE' ) ) ) ? mb_strtoupper( $_SERVER['REQUEST_METHOD'] ) : 'GET';
$method = ( isset( $_SERVER['REQUEST_METHOD'] ) and in_array( mb_strtoupper( $_SERVER['REQUEST_METHOD'] ), array( 'GET', 'POST', 'PUT', 'DELETE' ) ) ) ? mb_strtoupper( $_SERVER['REQUEST_METHOD'] ) : 'GET';
$params = array();
try
{
$endpointData = $this->_getEndpoint( $pathBits, $method );
}
catch ( \RuntimeException $e )
catch ( RuntimeException $e )
{
throw new \IPS\Api\Exception( 'NO_ENDPOINT', '2S291/1', 404 );
throw new Exception( 'NO_ENDPOINT', '2S291/1', 404 );
}
if ( method_exists( $this, "{$method}{$endpointData['endpoint']}" ) )
{
preg_match( '/^IPS\\\(.+?)\\\api\\\(.+?)$/', \get_called_class(), $matches );
preg_match( '/^IPS\\\(.+?)\\\api\\\(.+?)$/', get_called_class(), $matches );
$shouldLog = $this->shouldLog( $matches[1], $matches[2], "{$method}{$endpointData['endpoint']}" );
if ( !$this->canAccess( $matches[1], $matches[2], "{$method}{$endpointData['endpoint']}" ) )
{
throw new \IPS\Api\Exception( 'NO_PERMISSION', '2S291/7', 403, 'insufficient_scope' );
throw new Exception( 'NO_PERMISSION', '2S291/7', 403, 'insufficient_scope' );
}
$reflection = new \ReflectionMethod( $this, "{$method}{$endpointData['endpoint']}" );
$reflection = new ReflectionMethod( $this, "{$method}{$endpointData['endpoint']}" );
$docBlock = static::decodeDocblock( $reflection->getDocComment() );
if ( !$this->member )
{
if ( isset( $docBlock['details']['apimemberonly'] ) )
{
throw new \IPS\Api\Exception( 'NO_PERMISSION', '2S291/5', 403, 'insufficient_scope' );
throw new Exception( 'NO_PERMISSION', '2S291/5', 403, 'insufficient_scope' );
}
}
else
{
if ( isset( $docBlock['details']['apiclientonly'] ) )
{
throw new \IPS\Api\Exception( 'NO_PERMISSION', '2S291/6', 403, 'insufficient_scope' );
throw new Exception( 'NO_PERMISSION', '2S291/6', 403, 'insufficient_scope' );
}
}
@@ -181,7 +197,7 @@ abstract class _Controller
}
else
{
throw new \IPS\Api\Exception( 'BAD_METHOD', '3S291/2', 405 );
throw new Exception( 'BAD_METHOD', '3S291/2', 405 );
}
}
@@ -191,21 +207,21 @@ abstract class _Controller
* @param array $pathBits The parts to the path called
* @param string $method HTTP method verb
* @return array
* @throws \RuntimeException
* @throws RuntimeException
*/
protected function _getEndpoint( $pathBits, $method = 'GET' )
protected function _getEndpoint( array $pathBits, string $method = 'GET' ) : array
{
$endpoint = NULL;
$params = array();
if ( \count( $pathBits ) === 0 )
if ( count( $pathBits ) === 0 )
{
$endpoint = 'index';
}
elseif ( \count( $pathBits ) === 1 )
elseif ( count( $pathBits ) === 1 )
{
/* Sometimes we want to do something like /api/core/clubs/contenttypes but this is treated as an item */
if( \method_exists( $this, $method . $pathBits[0] ) )
if( method_exists( $this, $method . $pathBits[0] ) )
{
$endpoint = array_shift( $pathBits );
}
@@ -215,18 +231,18 @@ abstract class _Controller
$endpoint = 'item';
}
}
elseif ( \count( $pathBits ) === 2 )
elseif ( count( $pathBits ) === 2 )
{
$params[] = array_shift( $pathBits );
$endpoint = 'item_' . array_shift( $pathBits );
}
elseif ( \count( $pathBits ) === 3 )
elseif ( count( $pathBits ) === 3 )
{
$params[] = array_shift( $pathBits );
$endpoint = 'item_' . array_shift( $pathBits );
$params[] = array_shift( $pathBits );
}
elseif ( \count( $pathBits ) === 4 )
elseif ( count( $pathBits ) === 4 )
{
$params[] = array_shift( $pathBits );
$endpoint = 'item_' . array_shift( $pathBits );
@@ -235,7 +251,7 @@ abstract class _Controller
}
else
{
throw new \RuntimeException;
throw new RuntimeException;
}
return array( 'endpoint' => $endpoint, 'params' => $params );
@@ -248,17 +264,17 @@ abstract class _Controller
* @param bool $includeAll Should also disabled applications be returned
* @return array
*/
public static function getAllEndpoints( $type = NULL, $includeAll = FALSE )
public static function getAllEndpoints( ?string $type = NULL, bool $includeAll = FALSE ) : array
{
$return = array();
foreach ( \IPS\Application::applications() as $app )
foreach ( Application::applications() as $app )
{
if ( $app->enabled OR $includeAll )
{
$apiDir = $app->getApplicationPath() . '/api';
if ( file_exists( $apiDir ) )
{
$directory = new \DirectoryIterator( $apiDir );
$directory = new DirectoryIterator( $apiDir );
foreach ( $directory as $file )
{
if ( !$file->isDot() and mb_substr( $file, 0, 1 ) != '.' )
@@ -267,7 +283,7 @@ abstract class _Controller
$class = 'IPS\\' . $app->directory . '\\api\\' . $controllerName;
if( class_exists( $class ) )
{
$reflection = new \ReflectionClass( $class );
$reflection = new ReflectionClass( $class );
foreach ( $reflection->getMethods() as $method )
{
if ( $method->getName() != 'execute' and !$method->isStatic() and $method->isPublic() and mb_substr( $method->getName(), 0, 1 ) != '_' )
@@ -295,7 +311,7 @@ abstract class _Controller
* @param string $comment The docblock comment
* @return array
*/
public static function decodeDocblock( $comment )
public static function decodeDocblock( string $comment ) : array
{
$comment = explode( "\n", $comment );
array_shift( $comment );
@@ -350,31 +366,31 @@ abstract class _Controller
* @param bool $includeBaseUrl Whether or not to include the URL base in the endpoint URL
* @return string
*/
public static function parseEndpointForDisplay( $endpoint, $size='small', $includeBaseUrl=FALSE )
public static function parseEndpointForDisplay( string $endpoint, string $size='small', bool $includeBaseUrl=FALSE ) : string
{
$badgeStyles = array(
'GET' => 'ipsBadge_positive',
'POST' => 'ipsBadge_style2',
'DELETE' => 'ipsBadge_negative',
'PUT' => 'ipsBadge_intermediary'
'GET' => 'ipsBadge--positive',
'POST' => 'ipsBadge--style2',
'DELETE' => 'ipsBadge--negative',
'PUT' => 'ipsBadge--intermediary'
);
$pieces = explode( ' ', $endpoint );
if ( !\in_array( $pieces[0], array_keys( $badgeStyles ) ) )
if ( !in_array( $pieces[0], array_keys( $badgeStyles ) ) )
{
\IPS\Output::i()->error( \IPS\Member::loggedIn()->language()->addToStack( 'api_endpoint_phpdoc_error', FALSE, array( "sprintf" => array( $endpoint ) ) ), '3S291/4', 500 );
Output::i()->error( Member::loggedIn()->language()->addToStack( 'api_endpoint_phpdoc_error', FALSE, array( "sprintf" => array( $endpoint ) ) ), '3S291/4' );
}
$pieces[0] = "<span class='ipsBadge ipsBadge_{$size} " . $badgeStyles[ $pieces[0] ] . "'>" . $pieces[0] . "</span>";
$pieces[0] = "<span class='ipsBadge ipsBadge--{$size} " . $badgeStyles[ $pieces[0] ] . "'>" . $pieces[0] . "</span>";
if ( $includeBaseUrl )
{
if ( \IPS\Settings::i()->use_friendly_urls and \IPS\Settings::i()->htaccess_mod_rewrite )
if ( Settings::i()->use_friendly_urls and Settings::i()->htaccess_mod_rewrite )
{
$url = \IPS\Http\Url::external( rtrim( \IPS\Settings::i()->base_url, '/' ) . '/api' );
$url = Url::external( rtrim( Settings::i()->base_url, '/' ) . '/api' );
}
else
{
$url = \IPS\Http\Url::external( rtrim( \IPS\Settings::i()->base_url, '/' ) . '/api/index.php?' );
$url = Url::external( rtrim( Settings::i()->base_url, '/' ) . '/api/index.php?' );
}
$pieces[1] = $url . $pieces[1];
}