Skip to content

Commit

Permalink
updated markdown syntax
Browse files Browse the repository at this point in the history
  • Loading branch information
poef committed Feb 23, 2020
1 parent 4c60511 commit f57be01
Show file tree
Hide file tree
Showing 4 changed files with 44 additions and 35 deletions.
10 changes: 6 additions & 4 deletions docs/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,9 @@ This component provides a very basic http client using PHP stream handling.
--------------------
(string) \arc\http::get( $url = null, $query = null, $options = array() )

<?php
$htmlResult = \arc\http::get( 'http://www.ariadne-cms.org/', '?foo=bar' );
```php
$htmlResult = \arc\http::get( 'http://www.ariadne-cms.org/', '?foo=bar' );
```

These methods send a http requests to the given url with the given query arguments.
The options array is a optional list of [http context options](http://www.php.net/manual/en/context.http.php).
Expand All @@ -24,8 +25,9 @@ The options array is a optional list of [http context options](http://www.php.ne
--------------------
(string) \arc\http::request( $method = null, $url = null, $query = null, $options = array() )

<?php
$htmlResult = \arc\http::request( 'GET', 'http://www.ariadne-cms.org/', '?foo=bar' );
```php
$htmlResult = \arc\http::request( 'GET', 'http://www.ariadne-cms.org/', '?foo=bar' );
```

This method sends a http request with the given method to the given url with the given query arguments.
The options array is a optional list of [http context options](http://www.php.net/manual/en/context.http.php).
Expand Down
36 changes: 18 additions & 18 deletions docs/noxss.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,13 +7,13 @@ The `prevent()` method must be called at the end of handling any request.

Usage
-----
<?php
\arc\noxss::detect();
// handle request normally
\arc\noxss::prevent();
?>
```php
\arc\noxss::detect();

// handle request normally

\arc\noxss::prevent();
```

If any suspicious characters are found in any input argument, `detect()` will start an output buffer. `prevent()` will
check that buffer. If any of the suspicious input arguments are detected as-is in the buffer, `prevent()` will send a
Expand All @@ -22,17 +22,17 @@ check that buffer. If any of the suspicious input arguments are detected as-is i
If you want to handle the bad request yourself, you can pass a callback function to `prevent()`. It will only be called
in the case of a bad request and the only argument to the callback is the generated output.

<?php
\arc\noxss::detect();
// do your own stuff, load your routes, run your app, etc.
\arc\noxss::prevent(function($output) {
error_log('We are under attack!');
header('400 Bad Request');
echo '<h1>Bad Request, go home!</h1>';
});
?>
```php
\arc\noxss::detect();

// do your own stuff, load your routes, run your app, etc.

\arc\noxss::prevent(function($output) {
error_log('We are under attack!');
header('400 Bad Request');
echo '<h1>Bad Request, go home!</h1>';
});
```

Although you can potentially try to fix the output and strip out any offending content, you shouldn't. Any kind of
'cleaning' you do, can and will be used against you. Smart attackers will use your cleaning routine to do
Expand Down
14 changes: 10 additions & 4 deletions docs/route.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ arc\route

This component provides very basic URL routing. You could use it like this:

```php
$config = [
'/blog/' => function($remainder) {
if ( preg_match( '/(?<id>\d+)(?<format>\..+)?/', $remainder, $params ) ) {
Expand All @@ -28,31 +29,37 @@ This component provides very basic URL routing. You could use it like this:
}
];
$result = \arc\route::match('/blog/42.html', $config)['result'];
```

URL routing is a good way to implement a REST api, but in this form less usefull for a CMS system. Mostly because routes
are defined in code instead of user editable data. So use it with care.

`arc/route` doesn't implement parameter matching. The example above shows a very simple syntax using regular expressions
which is easy to learn and much more powerful than anything we could build. The most basic use works like this:

```php
if ( preg_match( '|(?<name>[^/]+)/|', $path, $params ) ) {
echo $params['name'];
}

```

The syntax `(?<name>` means that the expression following it, untill the next matching `)` will store its matching value
in `$params['name']`. You can use any regular expression inside it. In this case the actual regular expression used is
`[^/]+` which will match any character except `/`.

The `match()` method always returns an array with the following information:

```php
[
'path' => {matched path},
'remainder' => {the non matched remainder},
'result' => {the return value of the handler for the matched path}
]
```

You can create more complex routers by nesting the routing like this:

```php
$config = [
'/site/' => function($remainder) {
if ( preg_match( '|(?<name>[^/]+)(?<rest>.+)?|', $remainder, $params ) ) {
Expand All @@ -78,5 +85,4 @@ You can create more complex routers by nesting the routing like this:
}
];
$result = \arc\route::match('/site/mike/blog/', $config)['result'];
```
19 changes: 10 additions & 9 deletions docs/url.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@ arc/url

This component allows you to easily create and modify URL's. e.g.

```php5
<?php
```php
$url = \arc\url::url( 'http://www.ariadne-cms.org/' );
$url->path = '/docs/search/';
$url->query['searchstring'] = 'test';
echo $url; // => 'http://www.ariadne-cms.org/docs/search/?searchstring=test'
```

\arc\url::url
-------------
( \arc\url\Url ) \arc\url::url( (string) $url )
Expand All @@ -28,16 +28,18 @@ This method returns an object which has parsed the given url and contains proper
The query string is also automatically parsed to a PHPQuery object which implements ArrayObject. You can access any variable of the query string as an index in this array object or add new array entries. See the example above.
The query string is parsed with php's `parse_str` method, which doesn't understand all valid URL query parts. If you need to create a URL that isn't compatible with PHP, use `\arc\url::safeUrl()` instead. This will use an alternate parsing method that keeps the query string as it is.

The Url object and the PHPQuery object both have a __toString method so you can use the objects in echo/print statements.
The Url object and the PHPQuery object both have a \_\_toString method so you can use the objects in echo/print statements.

\arc\url::safeUrl
-----------------
( \arc\url\Url ) \arc\url::safeUrl( (string) $url )

This method is similar to `\arc\url::url()` but it returns a Url object with a 'safe' query parser. The difference is that the query part is not parsed with PHP's `parse_str()`, but with a custom parser that keeps all entries. This means that you can parse and create URL's which do not match PHP's query parsing rules, e.g.:

```php
http://www.example.com/?some+thing
http://www.example.com/?a=1&a=2
```

The first entry results in a query array with one entry: array('some thing')
The second entry results in array('a' => array('1','2'))
Expand All @@ -48,29 +50,28 @@ The second entry results in array('a' => array('1','2'))

Returns the named argument from the query part of the URL or null.

```php5
<?php
```php
$searchstring = $url->getvar('searchstring'); // => 'test' (see example url above)
$searchstring = $url->query->searchstring; // => 'test'
```

\arc\url\Url::putvar
--------------------------
(void) \arc\url\ParsedUrl::putvar( (string) $name, (mixed) $value )

Updates or inserts the named argument in the query part of the URL. All native PHP types are automaticall serialized into the correct query syntax.

```php5
<?php
```php
$url->putvar('searchstring', 'a new value');
$url->query->searchstring = 'a new value';
```

\arc\url\Url::import
--------------------------
(void) \arc\url\ParsedUrl::import( (mixed) $values )

Imports the given values and updates or inserts each value into the query part of the URL. The values argument can be either an array or a URL encoded string.

```php5
<?php
```php
$url->import( array( 'searchstring' => 'another value', 'argument2' => true ) );
```

0 comments on commit f57be01

Please sign in to comment.