From 17bc916fdcf257e3d095786c00cb4bfe3e6aaacb Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Wed, 29 Apr 2015 19:14:49 +0200 Subject: [PATCH 1/2] document usesession annotation --- developer_manual/app/controllers.rst | 99 ++++++++++++++++++--- developer_manual/app/users.rst | 127 +-------------------------- 2 files changed, 89 insertions(+), 137 deletions(-) diff --git a/developer_manual/app/controllers.rst b/developer_manual/app/controllers.rst index 76834fa5c..e58100ae8 100644 --- a/developer_manual/app/controllers.rst +++ b/developer_manual/app/controllers.rst @@ -209,9 +209,9 @@ It is possible to pass JSON using a POST, PUT or PATCH request. To do that the * } -Headers, files, cookies and environment variables -------------------------------------------------- -Headers, files, cookies and environment variables can be accessed directly from the request object. Every controller depends on the app name and the request object and sets both on protected attributes: +Reading headers, files, cookies and environment variables +--------------------------------------------------------- +Headers, files, cookies and environment variables can be accessed directly from the request object: .. code-block:: php @@ -223,25 +223,98 @@ Headers, files, cookies and environment variables can be accessed directly from class PageController extends Controller { - public function __construct($appName, IRequest $request) { - parent::__construct($appName, $request); - } - - public function someMethod() { - $type = $this->request->getHeader('Content-Type'); // $_SERVER['HTTP_CONTENT_TYPE'] $cookie = $this->request->getCookie('myCookie'); // $_COOKIES['myCookie'] $file = $this->request->getUploadedFile('myfile'); // $_FILES['myfile'] $env = $this->request->getEnv('SOME_VAR'); // $_ENV['SOME_VAR'] - - // access the app name - $name = $this->appName; } } -Why should those values be accessed from the request object and not from the global array like $_FILES? Simple: `because it's bad practice `_ +Why should those values be accessed from the request object and not from the global array like $_FILES? Simple: `because it's bad practice `_ and will make testing harder. + + +Reading and writing session variables +------------------------------------- +To set, get or modify session variables, the ISession object has to be injected into the controller. + +Then session variables can be accessed like this: + +.. note:: The session is closed automatically for writing, unless you add the @UseSession annotation! + +.. code-block:: php + + session = $session; + } + + /** + * The following annotation is only needed for writing session values + * @UseSession + */ + public function writeASessionVariable() { + // read a session variable + $value = $this->session['value']; + + // write a session variable + $this->session['value'] = 'new value'; + } + + } + + +Setting cookies +--------------- +Cookies can be set or modified directly on the response class: + +.. code-block:: php + + addCookie('foo', 'bar'); + $response->addCookie('bar', 'foo', new DateTime('2015-01-01 00:00')); + return $response; + } + + /** + * Invalidates the cookie "foo" + * Invalidates the cookie "bar" and "bazinga" + */ + public function invalidateCookie() { + $response = new TemplateResponse(...); + $response->invalidateCookie('foo'); + $response->invalidateCookies(array('bar', 'bazinga')); + return $response; + } + } + Responses ========= diff --git a/developer_manual/app/users.rst b/developer_manual/app/users.rst index 4d6405f96..74819b01d 100644 --- a/developer_manual/app/users.rst +++ b/developer_manual/app/users.rst @@ -1,6 +1,6 @@ -================================= -User, Session & Cookie Management -================================= +============== +Usermanagement +============== .. sectionauthor:: Bernhard Posselt @@ -171,124 +171,3 @@ Then users can be logged in by using: } - -Session Information -=================== -To set, get or modify session variables, the Session has to be injected from the ServerContainer: - -.. code-block:: php - - getContainer(); - - /** - * Controllers - */ - $container->registerService('SessionService', function($c) { - return new SessionService( - $c->query('Session'), - $c->query('TimeFactory') - ); - }); - - $container->registerService('Session', function($c) { - return $c->query('ServerContainer')->getSession(); - }); - - } - } - - -Then session variables can be accessed like this: - -.. code-block:: php - - session = $session; - } - - public function updateTimestamp() { - $oldTime = 0; - - if (array_key_exists('timestamp', $this->session) { - $oldTime = $this->session['timestamp']; - } - - $newTime = $this->timeFactory->getTime(); - if ($newTime > $oldTime) { - $this->session['timestamp'] = $newTime; - } - - } - - } - -Managing cookies -================ -To set, get or modify cookies the `request` variable and the `response` class can be used from within controllers: - -.. code-block:: php - - request->getCookie('bar'); - } - - /** - * Adds a cookie "foo" with value "bar" that expires after user closes the browser - * Adds a cookie "bar" with value "foo" that expires 2015-01-01 - */ - public function addCookie() { - $response = new TemplateResponse(...); - $response->addCookie('foo', 'bar'); - $response->addCookie('bar', 'foo', new \DateTime('2015-01-01 00:00')); - return $response; - } - - /** - * Invalidates the cookie "foo" - * Invalidates the cookie "bar" and "bazinga" - */ - public function invalidateCookie() { - $response = new TemplateResponse(...); - $response->invalidateCookie('foo'); - $response->invalidateCookies(array('bar', 'bazinga')); - return $response; - } - } From baf3902ab999945ea830bd7a9f3d6bb0e9632caf Mon Sep 17 00:00:00 2001 From: Bernhard Posselt Date: Wed, 29 Apr 2015 19:17:07 +0200 Subject: [PATCH 2/2] fix import --- developer_manual/app/controllers.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/developer_manual/app/controllers.rst b/developer_manual/app/controllers.rst index e58100ae8..8c706b516 100644 --- a/developer_manual/app/controllers.rst +++ b/developer_manual/app/controllers.rst @@ -288,6 +288,7 @@ Cookies can be set or modified directly on the response class: use DateTime; use OCP\AppFramework\Controller; + use OCP\AppFramework\Http\TemplateResponse; use OCP\IRequest; class BakeryController extends Controller {