Commit 171fdb44 authored by Niklas Fiekas's avatar Niklas Fiekas Committed by Crell

Detailed cleanup of documentation blocks for spacing, language, placement, etc.

parent 270dcd2e
......@@ -1537,15 +1537,17 @@ function request_uri($omit_query_string = FALSE) {
}
/**
* Returns the current global reuqest object.
* Returns the current global request object.
*
* @todo Replace this function with a proper dependency injection container.
*
* @staticvar Request $request
* @param Request $new_request
* The new request object to store. If you are not index.php, you probably
* should not be using this parameter.
* @return Request
* @staticvar Symfony\Component\HttpFoundation\Request $request
*
* @param Symfony\Component\HttpFoundation\Request $new_request
* Optional. The new request object to store. This parameter should only be
* used by index.php.
*
* @return Symfony\Component\HttpFoundation\Request
* The current request object.
*/
function request(Request $new_request = NULL) {
......
......@@ -480,10 +480,10 @@ function install_run_task($task, &$install_state) {
include_once DRUPAL_ROOT . '/core/includes/batch.inc';
$output = _batch_page();
// Because Batch API now returns a JSON response for intermediary steps,
// but the installer doesn't handle Response objects yet, we will just
// send the output here and emulate the old model.
// @todo: Replace this when we refactor the installer to use a
// Request/Response workflow.
// but the installer doesn't handle Response objects yet, just send the
// output here and emulate the old model.
// @todo Replace this when we refactor the installer to use a request-
// response workflow.
if ($output instanceof Response) {
$output->send();
$output = NULL;
......
......@@ -13,21 +13,24 @@
* This class is a central library for content type negotiation.
*
* @todo Replace this class with a real content negotiation library based on
* mod_negotiation. Development of that is a work in progress.
* mod_negotiation. Development of that is a work in progress.
*/
class ContentNegotiation {
/**
* Returns the normalized type of a given request.
* Gets the normalized type of a request.
*
* The normalized type is a short, lowercase version of the format, such as
* "html" or "json" or "atom".
* 'html', 'json' or 'atom'.
*
* @param Request $request
* @param Symfony\Component\HttpFoundation\Request $request
* The request object from which to extract the content type.
*
* @return
* The normalized type of a given request.
*/
public function getContentType(Request $request) {
// AJAX iframe uploads need special handling, because they contain a json
// AJAX iframe uploads need special handling, because they contain a JSON
// response wrapped in <textarea>.
if ($request->get('ajax_iframe_upload', FALSE)) {
return 'iframeupload';
......@@ -48,6 +51,4 @@ public function getContentType(Request $request) {
// Do HTML last so that it always wins.
return 'html';
}
}
......@@ -524,10 +524,9 @@ public function query($query, array $args = array(), $options = array()) {
}
catch (PDOException $e) {
if ($options['throw_exception']) {
// Wrap the exception in another exception. Its message is the extra
// database debug information. We have to do it this way because PHP
// does not allow us to override Exception::getMessage().
// Wrap the exception in another exception, because PHP does not allow
// overriding Exception::getMessage(). Its message is the extra database
// debug information.
$query_string = ($query instanceof DatabaseStatementInterface) ? $stmt->getQueryString() : $query;
$message = $e->getMessage() . ": " . $query_string . "; " . print_r($args, TRUE);
$exception = new DatabaseExceptionWrapper($message, 0, $e);
......
......@@ -2,7 +2,6 @@
/**
* @file
*
* Definition of Drupal\Core\DrupalKernel.
*/
......@@ -17,7 +16,6 @@
use Symfony\Component\EventDispatcher\Event;
use Symfony\Component\HttpKernel\Controller\ControllerResolverInterface;
use Symfony\Component\HttpKernel\Event\GetResponseForExceptionEvent;
//use Symfony\Component\HttpKernel\EventListener\RouterListener;
use Symfony\Component\HttpKernel\EventListener\ExceptionListener;
use Drupal\Core\EventSubscriber\ViewSubscriber;
use Drupal\Core\EventSubscriber\AccessSubscriber;
......@@ -39,25 +37,25 @@ class DrupalKernel extends HttpKernel {
/**
* The event dispatcher used by this kernel.
*
* @var EventDispatcherInterface
* @var Symfony\Component\EventDispatcher\EventDispatcherInterface
*/
protected $dispatcher;
/**
* The controller resolver that will extract the controller from a Request.
*
* @var ControllerResolverInterface
* @var Symfony\Component\HttpKernel\Controller\ControllerResolverInterface
*/
protected $resolver;
/**
* Constructor
* Constructor.
*
* @param EventDispatcherInterface $dispatcher
* An EventDispatcherInterface instance
* @param ControllerResolverInterface $resolver
* A ControllerResolverInterface instance
* @param Symfony\Component\EventDispatcher\EventDispatcherInterface $dispatcher
* An EventDispatcherInterface instance.
* @param Symfony\Component\HttpKernel\Controller\ControllerResolverInterface $resolver
* A ControllerResolverInterface instance.
*/
public function __construct(EventDispatcherInterface $dispatcher, ControllerResolverInterface $resolver) {
parent::__construct($dispatcher, $resolver);
......@@ -71,7 +69,7 @@ public function __construct(EventDispatcherInterface $dispatcher, ControllerReso
// @todo Make this extensible rather than just hard coding some.
// @todo Add a subscriber to handle other things, too, like our Ajax
// replacement system.
// replacement system.
$this->dispatcher->addSubscriber(new ViewSubscriber($negotiation));
$this->dispatcher->addSubscriber(new AccessSubscriber());
$this->dispatcher->addSubscriber(new MaintenanceModeSubscriber());
......@@ -82,7 +80,7 @@ public function __construct(EventDispatcherInterface $dispatcher, ControllerReso
$this->dispatcher->addSubscriber(new RequestCloseSubscriber());
// Some other form of error occured that wasn't handled by another kernel
// listener. That could mean that it's a method/mime-type/error
// listener. That could mean that it's a method/mime-type/error
// combination that is not accounted for, or some other type of error.
// Either way, treat it as a server-level error and return an HTTP 500.
// By default, this will be an HTML-type response because that's a decent
......
......@@ -13,8 +13,7 @@
/**
* @file
*
* Definition of Drupal\Core\EventSubscriber\AccessSubscriber
* Definition of Drupal\Core\EventSubscriber\AccessSubscriber.
*/
/**
......@@ -26,9 +25,9 @@ class AccessSubscriber implements EventSubscriberInterface {
* Verifies that the current user can access the requested path.
*
* @todo This is a total hack to keep our current access system working. It
* should be replaced with something robust and injected at some point.
* should be replaced with something robust and injected at some point.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function onKernelRequestAccessCheck(GetResponseEvent $event) {
......
......@@ -19,7 +19,7 @@ class FinishResponseSubscriber implements EventSubscriberInterface {
/**
* Sets extra headers on successful responses.
*
* @param FilterResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\FilterResponseEvent $event
* The event to process.
*/
public function onRespond(FilterResponseEvent $event) {
......
<?php
/**
* @file
* Definition of Drupal\Core\EventSubscriber\MaintenanceModeSubscriber.
*/
namespace Drupal\Core\EventSubscriber;
use Symfony\Component\HttpFoundation\Response;
......@@ -7,11 +12,6 @@
use Symfony\Component\HttpKernel\Event\GetResponseEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
/**
* @file
* Definition of Drupal\Core\EventSubscriber\MaintenanceModeSubscriber.
*/
/**
* Maintenance mode subscriber for controller requests.
*/
......@@ -20,7 +20,7 @@ class MaintenanceModeSubscriber implements EventSubscriberInterface {
/**
* Response with the maintenance page when the site is offline.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function onKernelRequestMaintenanceModeCheck(GetResponseEvent $event) {
......
......@@ -27,5 +27,4 @@ public function setPath(Request $request, $path) {
// object directly.
_current_path($path);
}
}
......@@ -2,8 +2,7 @@
/**
* @file
*
* Definition of Drupal\Core\EventSubscriber\PathSubscriber
* Definition of Drupal\Core\EventSubscriber\PathSubscriber.
*/
namespace Drupal\Core\EventSubscriber;
......@@ -21,14 +20,13 @@ class PathSubscriber extends PathListenerBase implements EventSubscriberInterfac
/**
* Resolve the system path.
*
* @todo The path system should be objectified to remove the function calls
* in this method.
* @todo The path system should be objectified to remove the function calls in
* this method.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function onKernelRequestPathResolve(GetResponseEvent $event) {
$request = $event->getRequest();
$path = $this->extractPath($request);
......@@ -41,10 +39,10 @@ public function onKernelRequestPathResolve(GetResponseEvent $event) {
/**
* Resolve the front-page default path.
*
* @todo The path system should be objectified to remove the function calls
* in this method.
* @todo The path system should be objectified to remove the function calls in
* this method.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function onKernelRequestFrontPageResolve(GetResponseEvent $event) {
......@@ -63,10 +61,9 @@ public function onKernelRequestFrontPageResolve(GetResponseEvent $event) {
* Decode language information embedded in the request path.
*
* @todo Refactor this entire method to inline the relevant portions of
* drupal_language_initialize(). See the inline comment for more
* details.
* drupal_language_initialize(). See the inline comment for more details.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function onKernelRequestLanguageResolve(GetResponseEvent $event) {
......@@ -93,15 +90,15 @@ public function onKernelRequestLanguageResolve(GetResponseEvent $event) {
*
* Parameters in the URL sometimes represent code-meaningful strings. It is
* therefore useful to always urldecode() those values so that individual
* controllers need not concern themselves with it. This is Drupal-specific
* logic, and may not be familiar for developers used to other Symfony-family
* controllers need not concern themselves with it. This is Drupal-specific
* logic and may not be familiar for developers used to other Symfony-family
* projects.
*
* @todo Revisit whether or not this logic is appropriate for here or if
* controllers should be required to implement this logic themselves. If
* we decide to keep this code, remove this TODO.
* controllers should be required to implement this logic themselves. If we
* decide to keep this code, remove this TODO.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function onKernelRequestDecodePath(GetResponseEvent $event) {
......
<?php
/**
* @file
* Definition of Drupal\Core\EventSubscriber\RequestCloseSubscriber.
*/
namespace Drupal\Core\EventSubscriber;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\HttpKernel\Event\PostResponseEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
/**
* @file
*
* Definition of Drupal\Core\EventSubscriber\RequestCloseSubscriber;
*/
/**
* Subscriber for all responses.
*/
......@@ -22,16 +20,16 @@ class RequestCloseSubscriber implements EventSubscriberInterface {
* Performs end of request tasks.
*
* @todo The body of this function has just been copied almost verbatim from
* drupal_page_footer(), with the exception of now passing the response
* content to drupal_page_set_cache(). There's probably a lot in here that
* needs to get removed/changed.
* drupal_page_footer(), with the exception of now passing the response
* content to drupal_page_set_cache(). There's probably a lot in here that
* needs to get removed/changed.
*
* @param PostResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\PostResponseEvent $event
* The Event to process.
*/
public function onTerminate(PostResponseEvent $event) {
global $user;
module_invoke_all('exit');
// Commit the user session, if needed.
......
......@@ -2,7 +2,6 @@
/**
* @file
*
* Definition of Drupal\Core\EventSubscriber\RouterListener;
*/
......@@ -17,7 +16,6 @@
use Symfony\Component\Routing\Exception\ResourceNotFoundException;
use Symfony\Component\Routing\Exception\MethodNotFoundException;
/**
* Drupal-specific Router listener.
*
......@@ -40,7 +38,7 @@ public function __construct(UrlMatcherInterface $urlMatcher, LoggerInterface $lo
* This method is nearly identical to the parent, except it passes the
* $request->attributes->get('system_path') variable to the matcher.
* That is where Drupal stores its processed, de-aliased, and sanitized
* internal path. We also pass the full request object to the URL Matcher,
* internal path. We also pass the full request object to the URL Matcher,
* since we want attributes to be available to the matcher and to controllers.
*/
public function onKernelRequest(GetResponseEvent $event) {
......@@ -80,5 +78,4 @@ public function onKernelRequest(GetResponseEvent $event) {
throw new MethodNotAllowedHttpException($e->getAllowedMethods(), $message, $e);
}
}
}
<?php
/**
* @file
* Definition of Drupal\Core\EventSubscriber\ViewSubscriber.
*/
namespace Drupal\Core\EventSubscriber;
use Symfony\Component\HttpFoundation\Response;
......@@ -14,12 +19,6 @@
use Drupal\Core\ContentNegotiation;
/**
* @file
*
* Definition of Drupal\Core\EventSubscriber\ViewSubscriber;
*/
/**
* Main subscriber for VIEW HTTP responses.
*/
......@@ -40,7 +39,7 @@ public function __construct(ContentNegotiation $negotiation) {
* from an JSON-type response is a JSON string, so just wrap it into a
* Response object.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function onView(GetResponseEvent $event) {
......@@ -60,8 +59,6 @@ public function onView(GetResponseEvent $event) {
public function onJson(GetResponseEvent $event) {
$page_callback_result = $event->getControllerResult();
//print_r($page_callback_result);
$response = new JsonResponse();
$response->setContent($page_callback_result);
......@@ -104,12 +101,12 @@ public function onIframeUpload(GetResponseEvent $event) {
* Processes a successful controller into an HTTP 200 response.
*
* Some controllers may not return a response object but simply the body of
* one. The VIEW event is called in that case, to allow us to mutate that
* body into a Response object. In particular we assume that the return
* from an HTML-type response is a render array from a legacy page callback
* and render it.
* one. The VIEW event is called in that case, to allow us to mutate that
* body into a Response object. In particular we assume that the return from
* an HTML-type response is a render array from a legacy page callback and
* render it.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function onHtml(GetResponseEvent $event) {
......
......@@ -2,7 +2,6 @@
/**
* @file
*
* Definition of Drupal\Core\ExceptionController.
*/
......@@ -29,24 +28,24 @@ class ExceptionController {
*
* We will use this to fire subrequests as needed.
*
* @var HttpKernelInterface
* @var Symfony\Component\HttpKernel\HttpKernelInterface
*/
protected $kernel;
/**
* The
* The content negotiation library.
*
* @var ContentNegotiation
* @var Drupal\Core\ContentNegotiation
*/
protected $negotiation;
/**
* Constructor
* Constructor.
*
* @param HttpKernelInterface $kernel
* @param Symfony\Component\HttpKernel\HttpKernelInterface $kernel
* The kernel that spawned this controller, so that it can be reused
* for subrequests.
* @param ContentNegotiation $negotiation
* @param Drupal\Core\ContentNegotiation $negotiation
* The content negotiation library to use to determine the correct response
* format.
*/
......@@ -58,15 +57,15 @@ public function __construct(HttpKernelInterface $kernel, ContentNegotiation $neg
/**
* Handles an exception on a request.
*
* @param FlattenException $exception
* @param Symfony\Component\HttpKernel\Exception\FlattenException $exception
* The flattened exception.
* @param Request $request
* @param Symfony\Component\HttpFoundation\Request $request
* The request that generated the exception.
* @return \Symfony\Component\HttpFoundation\Response
*
* @return Symfony\Component\HttpFoundation\Response
* A response object to be sent to the server.
*/
public function execute(FlattenException $exception, Request $request) {
$method = 'on' . $exception->getStatusCode() . $this->negotiation->getContentType($request);
if (method_exists($this, $method)) {
......@@ -74,13 +73,12 @@ public function execute(FlattenException $exception, Request $request) {
}
return new Response('A fatal error occurred: ' . $exception->getMessage(), $exception->getStatusCode());
}
/**
* Processes a MethodNotAllowed exception into an HTTP 405 response.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function on405Html(FlattenException $exception, Request $request) {
......@@ -90,7 +88,7 @@ public function on405Html(FlattenException $exception, Request $request) {
/**
* Processes an AccessDenied exception into an HTTP 403 response.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function on403Html(FlattenException $exception, Request $request) {
......@@ -130,7 +128,7 @@ public function on403Html(FlattenException $exception, Request $request) {
*
* @param FlattenException $exception
* Metadata about the exception that was thrown.
* @param Request $request
* @param Symfony\Component\HttpFoundation\Request $request
* The request object that triggered this exception.
*/
public function on500Html(FlattenException $exception, Request $request) {
......@@ -179,24 +177,21 @@ public function on500Html(FlattenException $exception, Request $request) {
}
drupal_set_title(t('Error'));
// We fallback to a maintenance page at this point, because the page generation
// itself can generate errors.
// We fallback to a maintenance page at this point, because the page
// generation itself can generate errors.
$output = theme('maintenance_page', array('content' => t('The website encountered an unexpected error. Please try again later.')));
$response = new Response($output, 500);
$response->setStatusCode(500, '500 Service unavailable (with message)');
return $response;
//return _drupal_log_error(_drupal_decode_exception($exception), TRUE);
}
/**
* This method is a temporary port of _drupal_decode_exception().
*
* @todo This should get refactored. Flatten Exception could use some
* improvement as well.
* @todo This should get refactored. FlattenException could use some
* improvement as well.
*
* @return array
*/
......@@ -257,7 +252,6 @@ protected function decodeException(FlattenException $exception) {
* An associative array with keys 'file', 'line' and 'function'.
*/
protected function getLastCaller($backtrace) {
// Ignore black listed error handling functions.
$blacklist = array('debug', '_drupal_error_handler', '_drupal_exception_handler');
......@@ -290,7 +284,7 @@ protected function getLastCaller($backtrace) {
/**
* Processes a NotFound exception into an HTTP 403 response.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function on404Html(FlattenException $exception, Request $request) {
......@@ -309,10 +303,10 @@ public function on404Html(FlattenException $exception, Request $request) {
$path = drupal_get_normal_path(variable_get('site_404', ''));
if ($path && $path != $system_path) {
// @todo: Um, how do I specify an override URL again? Totally not clear.
// Do that and sub-call the kernel rather than using meah().
// @todo: The create() method expects a slash-prefixed path, but we
// store a normal system path in the site_404 variable.
// @todo Um, how do I specify an override URL again? Totally not clear. Do
// that and sub-call the kernel rather than using meah().
// @todo The create() method expects a slash-prefixed path, but we store a
// normal system path in the site_404 variable.
$subrequest = Request::create('/' . $path, 'get', array(), $request->cookies->all(), array(), $request->server->all());
$response = $this->kernel->handle($subrequest, HttpKernelInterface::SUB_REQUEST);
......@@ -337,7 +331,7 @@ public function on404Html(FlattenException $exception, Request $request) {
/**
* Processes an AccessDenied exception into an HTTP 403 response.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function on403Json(FlattenException $exception, Request $request) {
......@@ -349,7 +343,7 @@ public function on403Json(FlattenException $exception, Request $request) {
/**
* Processes a NotFound exception into an HTTP 404 response.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function on404Json(FlattenException $exception, Request $request) {
......@@ -361,7 +355,7 @@ public function on404Json(FlattenException $exception, Request $request) {
/**
* Processes a MethodNotAllowed exception into an HTTP 405 response.
*
* @param GetResponseEvent $event
* @param Symfony\Component\HttpKernel\Event\GetResponseEvent $event
* The Event to process.
*/
public function on405Json(FlattenException $exception, Request $request) {
......@@ -369,5 +363,4 @@ public function on405Json(FlattenException $exception, Request $request) {
$response->setStatusCode(405, 'Method Not Allowed');
return $response;
}
}
......@@ -2,7 +2,6 @@
/**
* @file
*
* Definition of Drupal\Core\UrlMatcher.
*/
......@@ -25,7 +24,7 @@ class UrlMatcher implements UrlMatcherInterface {
/**
* The request context for this matcher.
*
* @var RequestContext
* @var Symfony\Component\Routing\RequestContext
*/
protected $context;
......@@ -49,8 +48,8 @@ public function __construct() {
* The request context object does not contain the information we need, so
* we will use the original request object.
*
* @param RequestContext $context
* The context
* @param Symfony\Component\Routing\RequestContext $context
* The context.
*
* @api
*/
......@@ -65,8 +64,8 @@ public function setContext(RequestContext $context) {
* The request context object does not contain the information we need, so
* we will use the original request object.
*
* @return RequestContext
* The context
* @return Symfony\Component\Routing\RequestContext
* The context.
*/
public function getContext() {
return $this->context;
......@@ -109,7 +108,7 @@ public function match($pathinfo) {
* Get a drupal menu item.
*
* @todo Make this return multiple possible candidates for the resolver to
* consider.
* consider.
*
* @param string $path
* The path being looked up by
......@@ -128,10 +127,10 @@ protected function convertDrupalItem($router_item) {
);
// Place argument defaults on the route.
// @todo: For some reason drush test runs have a serialized page_arguments
// but HTTP requests are unserialized. Hack to get around this for now.
// This might be because page arguments aren't unserialized in
// menu_get_item() when the access is denied.
// @todo For some reason drush test runs have a serialized page_arguments
// but HTTP requests are unserialized. Hack to get around this for now.
// This might be because page arguments aren't unserialized in
// menu_get_item() when the access is denied.
!is_array($router_item['page_arguments']) ? $page_arguments = unserialize($router_item['page_arguments']) : $page_arguments = $router_item['page_arguments'];
foreach ($page_arguments as $k => $v) {
$route[$k] = $v;
......
......@@ -24,12 +24,12 @@
require_once DRUPAL_ROOT . '/core/includes/bootstrap.inc';
drupal_bootstrap(DRUPAL_BOOTSTRAP_CONFIGURATION);
// A request object from the HTTPFoundation to tell us about the request.
// Create a request object from the HTTPFoundation.
$request = Request::createFromGlobals();
// Set the global $request object. This is a temporary measure to
// keep legacy utility functions working. It should be moved to a dependency
// injection container at some point.
// Set the global $request object. This is a temporary measure to keep legacy
// utility functions working. It should be moved to a dependency injection
// container at some point.
request($request);
drupal_bootstrap(DRUPAL_BOOTSTRAP_CODE);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment