phalcon-orphanage/docs

Phalcon Framework documentation

docs's Issues

Typo (Volt: Template Engine) Documentation

Missing closing % in Tests More examples. See screen shot.

http://phalcon-php-framework-documentation.readthedocs.org/en/latest/reference/volt.html#if

doc has error? i'm not sure

http://docs.phalconphp.com/en/latest/reference/di.html

"localhost", "username" => "root", "password" => "secret", "dbname" => "invo" )); } /** * Creates a connection only once and returns it */ public static function getSharedConnection() { if (self::$_connection===null){ $connection = self::_createConnection(); self::$_connection = $connection; } return self::$_connection; } /** * Always returns a new connection */ public static function getNewConnection() { return self::_createConnection(); } ``` } class SomeComponent { ``` protected $_connection; /** * Sets the connection externally */ public function setConnection($connection){ $this->_connection = $connection; } /** * This method always needs the shared connection */ public function someDbTask() { $connection = $this->_connection; // ... } /** * This method always needs a new connection */ public function someOtherDbTask($connection) { } ``` } $some = new SomeComponent(); //This injects the shared connection $some->setConnection(Registry::getSharedConnection()); $some->someDbTask(); //Here, we always pass a new connection as parameter $some->someOtherDbTask(Registry::getConnection()); // Registry::getNewConnection(); ?

[NFR] Add phpdoc comments in C sources of available properties

@property-read if property is available through getter method
@property-write if property is available through setter method
@property if property is public or available through getter and setter methods

For example in (acl/adapter/memory.c):

/**
 * Phalcon\Acl\Adapter\Memory
 *
 * Manages ACL lists in memory
 *
 * ... description and usage examples
 *
 * @property-read Phalcon\Acl\Role[] $roles An array with every role registered in the list
 * @property-read Phalcon\Acl\Resource[] $resources An array with every resource registered in the list
 */

Typo - Abstract class Phalcon\Text

https://github.com/phalcon/docs/blob/master/en/api/Phalcon_Text.rst

The example for uncamelize shows Phalcon\Text::camelize

Tutorial 1 documentation - code block modification

I ran into the issue described in #90 (Phalcon\Tag::linkTo - subfolder missing from URL) and eventually found the code snippet to resolve it.

$di->set('url', function(){
     $url = new \Phalcon\Mvc\Url();
     $url->setBaseUri('/tutorial/');
     return $url;
});

Please can the above code be added to the code block in the Tutorial 1 documentation so that it matches the suggested file/folder structure. That way newcomers won't be stumbling at the first hurdle.

Many thanks.

Mention how Models get mapped to tables

The docs state models should be named with camelCase. Not mentioned is the fact that camelCase is required because that's how Phalcon determines what table to map to.

For example, I had a table called access_log. All the documentation has single-word models and tables, so I wasn't sure how to name my accompanying model to ensure it maps toaccess_log. I tried Access_Log but it added an extra underline.

Just a mention in the docs that says something to the effect of "If your model name has multiple words, Phalcon will separate those words with underscores to determine the database table to map to".

"Typo in column define options" fix caused table corrupt.

Guys, c'mon. The error is still there - http://docs.phalconphp.com/en/latest/reference/db.html#creating-tables. @xboston #298 changed word, but crashed the whole table.

Volt filters: default

Volt filters docs say:

default Sets a default value in case that the evaluated expression is null

Actually, the generated PHP code for {{ var|default('?') }} looks like this:

<?php echo (empty($var) ? ('?') : ($var)); ?>

which means that $var can be 0, null, false, '' and even not defined at all. Since this behavior is very useful, I assume that's a bug in the docs and should be corrected to:

default Sets a default value in case that the evaluated expression is empty (is not set or evaluates to a falsy value)

X_REQUESTED_WITH missing HTTP in front

In the router docs it shows the use of X_REQUESTED_WITH in relation to detect ajax calls. This should be HTTP_X_REQUESTED_WITH

Enhanche EventsManager documentation

(from here: phalcon/cphalcon#1980)

The Events Manageer page needs improvements:

• No examples on how to use it with DI, like on other pages. Usually people want it with the framework, not as an individual component. Need examples on how to, for instance, integrate it with 'dispatch'.
• Need to outline that even when you use FactoryDefault, services are not bound to the eventsManager service by default! This has reasons, but the default DI pretends to be full of features, and it's strange to see some of them missing.

These are trivial, but not obvious for newcomers.

Missed example "Choose template to render" in the annotations.rst

The article has a title and introduction, but the example is missing.

https://github.com/phalcon/docs/blob/d1c87bfdb83841bd06adda9de1bffec2e986577f/en/reference/annotations.rst#choose-template-to-render

fixed wrong key names

3321f96eb81b970bea820d5b91f95c195b15de6e

Incorrect/incomplete documentation about Pdo adapter

This page:https://github.com/phalcon/docs/blob/master/en/api/Phalcon_Db_Adapter_Pdo.rst

The code example for executePrepared() does not have the 3rd required parameter.

Neither does the MySQL adapter example: https://github.com/phalcon/docs/blob/master/en/api/Phalcon_Db_Adapter_Pdo_Mysql.rst.

Spelling Errata

There are a noticeable amount of errata in documentation, a spell-checker software will unearth them to you.

Not apparent in tutorial.rst that each view needs to be an index.html within a folder with the controller prefix

https://github.com/phalcon/docs/blob/master/en/reference/tutorial.rst

The initial information about views indicates that the structure is view/index.phtml rather than what it should be index/index.phtml meaning when you come to add the signup view, you expect to use views/signup.phtml instead of what you should use views/signup/index.phtml.

A simple sentence explaining this would have saved me half an hour or guessing.

[BUG] Wildcard roles in ACL

Documentation for ACL says a * wildcard is allowable:

 //Allow access to any role to browse on products
 $acl->allow('*', 'products', 'browse');

 //Allow access to any role to browse on any resource
 $acl->allow('*', '*', 'browse');

But an exception gets thrown. This was mentioned in the forum: http://forum.phalconphp.com/discussion/423/are-there-wildcards-in-acl-roles- but not acted on

[NFR] Default values of method parameters in documentation

It would be great to see default values of method parameters in documentation, instead of searching them in source code.

Mass assignment in tutorial

https://github.com/phalcon/docs/blob/master/en/reference/tutorial.rst#storing-data-using-models

$user->save($_POST)

If you pass e.g. is_admin it will set value in DB, if no validation is done.

Correct?

incorrect sample code on "Encryption/Decryption" page

http://docs.phalconphp.com/en/latest/reference/crypt.html#base64-support

Current:

echo $crypt->decryptBase64($text, $key);

Correctly:

echo $crypt->decryptBase64($encrypt, $key);

Wrong label for the E-Mail field

Just a small typo in this page
http://docs.phalconphp.com/en/latest/reference/tutorial.html#designing-a-sign-up-form

this line
E-Mail

should be
E-Mail

:)

Parameter of Phalcon\Http\Request::getJsonRawBody() is not documented

Phalcon\Http\Request::getJsonRawBody() has parameter $assoc but this is not documented.

https://github.com/phalcon/cphalcon/blob/master/ext/http/request.c#L959
https://github.com/phalcon/docs/blob/master/en/api/Phalcon_Http_Request.rst

Is there any problem with doc comment or gen-api.php?

Has 'transifex.com' been deprecated?

I has wrote some Chinese translation to 'transifex.com' on 3 days ago, but it's still with 'UNREVIEWED' status. Has 'transifex.com' been deprecated ? whether I must push them to Github? My 'transifex.com' ID is 'mr5'.

Fix installing instruction for Phalcon Developer Tools on Mac OS X: .profile is sometimes ignored

The instruction says to insert these two lines at the end of ~/.profile:

export PATH=$PATH:/Users/scott/phalcon-tools
export PTOOLSPATH=/Users/scott/phalcon-tools

Didn't work for me.

Turns out if you have .bash_profile or .bash_login files, then your .profile will be ignored by bash.

I fixed it by inserting the two lines into ./bash_login

Assets\Manager: VERY incomplete

Assets page lacks the following:

• Examples on how to add assets and output them from templates
• Real-life minifying example (see this issue from volt
• Configuration options: sourceBasePath, targetBasePath

API page for \Assets\Manager lacks the following:

• Configuration options: sourceBasePath, targetBasePath
• Method output() is completely missing

API page for \Assets\Collection:

• Method setPrefix() is missing

Too bad users have to look into the sources to learn the above.

Need to add file location to the examples

Going through the REST app tutorial I could not determine which file the example code should be placed in, starting at http://docs.phalconphp.com/en/latest/reference/tutorial-rest.html#retrieving-data
we should place a comment in each example ie:
//app/models/Robots.php
or
//public/index.php
or write in the instructions the following examples should be placed in this file.

[BUG] Validation page

http://docs.phalconphp.com/en/latest/reference/validation.html#validators

The list of built-in validators is missing. It is present in the 1.2.2 documentation.

phalcon mvc view doc

Example on the page
http://docs.phalconphp.com/en/latest/api/Phalcon_Mvc_View.html

view->setRenderLevel(View::LEVEL_VIEW); ``` constant LEVEL_VIEW dosen't exist should be LEVEL_ACTION_VIEW

Images not working in latest documentation

The images in the latest documentation are showing as relative URLs printed in the page instead of displaying the images.

Example:
http://docs.phalconphp.com/en/latest/reference/tutorial-invo.html
Under Project Structure, I see the following line: reference/../static/img/invo-1.png
The image does exist at http://docs.phalconphp.com/en/latest/static/img/invo-1.png
The path should be either prepended with /en/latest/ or have reference/ removed.

Other pages are affected as well:
http://docs.phalconphp.com/en/latest/reference/migrations.html
http://docs.phalconphp.com/en/latest/reference/tools.html

Register dir in REST API page

A little piece of information is missing from this page:
http://docs.phalconphp.com/en/latest/reference/tutorial-rest.html

It is not mentioned to register the dirs in Loader for example models etc.
Here is a bit explanation:
http://forum.phalconphp.com/discussion/1277/rest-api-notfound-problem#C4551

Thanks

docs on readthedocs are no longer updated on commit

@phalcon @xboston seems like the repo no longer matches the docs on readthedocs

Describe the magic initialize() method

Throughout the docs, the magic initialize() method is mentioned. Need to describe further when it's called and which classes support it.

Example: Using Controllers

Router default parameter value

Hi, defined a route like this:

$router->add('/{date}', [
'controller' => 'index',
'action' => 'index',
'defaults' => [
'date' => 'today'
]
]);

and var_dump in action seems to pick up it correctly but handle() method in front controller seem to have problem with it:

Warning: Illegal offset type in /Users/aleksander/php/kociouek/public/index.php on line 27
Call Stack

Time Memory Function Location

1 0.0002 239888 {main}( ) ../index.php:0
2 0.0010 270800 handle ( ) ../index.php:27
3 0.0012 276496 handle ( ) ../index.php:27

Incorrect URL in screenshots

The following files have the directory "test" in the URL, but they should have "tutorial":

https://github.com/Pajamaman/docs/blob/master/en/_static/img/tutorial-1.png
https://github.com/Pajamaman/docs/blob/master/en/_static/img/tutorial-2.png
https://github.com/Pajamaman/docs/blob/master/en/_static/img/tutorial-3.png
https://github.com/Pajamaman/docs/blob/master/en/_static/img/tutorial-4.png

I would fix this myself but I don't have the bandwidth to clone the repo.

This goes for other languages as well.

Duplicated Symfony version in the Hello World

At the Hello World chapter (http://docs.phalconphp.com/en/latest/reference/benchmark/hello-world.html) Symfony is quoted with the 2.0.11 version, but below the 2.1.6 version is "used", which is the correct one?

Typo in column define options

Here http://docs.phalconphp.com/en/latest/reference/db.html#creating-tables in a table with description of options available to define a column is a little typo.
For a row with option "primary" description should be "True if the column is part of the table’s primary key" and now it's "True if the table is part of the table’s primary key".

Custom View Helpers example.

Creating your own helpers section does not cover where to put created helper.

Use simple quote instead of double quote in documentation

Hello,

Did you know double quotes consumes more than simple quote ? When you use double quotes, PHP verify the string to verify the existence of variables, example:

$name = 'S';
$test = "Hello $name";
echo $test;

Result: Hello S

with simple quote, PHP don't do this verification:

$name = 'S';
$test = 'Hello $name';
echo $test;

Result: Hello $name

$name = 'S';
$test = 'Hello ' . $name;
echo $test;

Result: Hello S

So I think you should replace any unnecessary double quotes in your documentation by single quote to gain performance boost ! :)

Possible necessary addition to PHQL docs

Hi,

I'm using PHQL in my command line application. When I used this:

$Query = new Phalcon\Mvc\Model\Query($sql, $this->di);

I got an error saying wrong number of errors, and that "PHQL Statement cannot be NULL".

When I changed that to

$Query = $this->modelsManager->createQuery($sql);

The query ran just fine.

So, is this a failure of MY code, a bug in Phalcon, or an omission in the docs?

[BUG] \Phalcon\Mvc\View::render() must take at least 2 arguments

The documentation says one should pass the path like so:

$this->view->render('posts/show');

When in reality the controller and action must be passed separately:

$this->view->render('posts','show');

Foreign language document

Hi.

I want to build document other than English.
For example, Japanese, Russian , French etc.
Could you configure as such in the Sphinx?

example)
https://github.com/phalcon/docs/tree/master/ja
--> http://docs.phalconphp.com/ja/latest/

thanks

Incomplete API docs

After the 2.0 release, someone should compare the API docs with the source to resolve the following:

• Missing methods (see #334)
• Wrong descriptions (copy-pasted and not fixed)
• Wrong argument types & return types
• The most annoying: most classes do not document their options (also see #334). If some function accepts an array, the user needs to know an array of what is expected at the input.

Issues with the micro version

Hello,

There are some issues with the micro version :

This is the code snippet :

//Return a rendered view
$app->get('/products/show', function() use ($app) {

// Render app/views/products/show.phtml passing some variables
echo $app['view']->render('products/show', array(
        'id' => 100,
        'name' => 'Artichoke'
    ));

});

with echo : PHP Catchable fatal error: Object of class Phalcon\Mvc\View could not be converted to string

I tried to replace echo with "return" and I got this

PHP Fatal error: Call to undefined function Phalcon\Mvc\View::issent()

on
$app->handle();

Typo

in http://docs.phalconphp.com/en/latest/reference/tags.html#creating-forms

"5")) ?> "6", "rows" => 20)) ?> "5") ?>

should be changed to:

"5")) ?> "6", "rows" => 20)) ?> "5") ?>

also usage of "Nice article" is not clear.

Error in the last example of PHQL / Joins

I'm trying to find a way to generate sql from phql, so far without luck. The last example in PHQL#Joins says that:

$phql = 'SELECT Brands.name, Songs.name FROM Artists ' .
        'JOIN Songs WHERE Artists.genre = "Trip-Hop"';
$result = $this->modelsManager->query($phql);

Produce the following SQL in MySQL:

SELECT `brands`.`name`, `songs`.`name` FROM `artists`
INNER JOIN `albums` ON `albums`.`artists_id` = `artists`.`id`
INNER JOIN `songs` ON `albums`.`songs_id` = `songs`.`id`
WHERE `artists`.`genre` = 'Trip-Hop'

Does it demonstrate what happens in MySql or does it actually sets $result value to that string?

The error seems to be the missing query method, perhaps the executeQuery was meant?

Wrong graph data in benchmark

The data in the first two graphs of "Hello World Benchmark" differ from the shown benchmarks: While the benchmark for Yii shows 961.28 requests/s, the first graph shows only 851,83. The second graph shows a value of 1,174 ms/request for Yii, while the benchmark shows 1,040 ms/request, Data for other frameworks seem to be correct, but not for Yii.

Code block isn't styled properly

Volt syntax code here is shown without code syntax stylement around it.

Screenshot:

Router API page: missing methods

The Router API page is missing a method:

• getMatchedRoute()

Found it here: http://forum.phalconphp.com/discussion/262/currently-dispatching-route-name

Micro Redirect

Documentation is needed to be fixed http://docs.phalconphp.com/en/latest/reference/micro.html#making-redirections

phalcon/cphalcon#1717

"Typo in column define options" fix caused table corrupt.

Fixing #297 caused table disappear - http://docs.phalconphp.com/en/latest/reference/db.html#creating-tables. | at the end of line "primary" vanished.

incorrect sample code on "Assets Management" page

http://docs.phalconphp.com/en/latest/reference/assets.html#minification-filtering

    ->addJs('code.jquery.com/jquery-1.10.0.min.js', true, false)

correctly:

    ->addJs('http://code.jquery.com/jquery-1.10.0.min.js', false, false)

Used Phalcon version: v1.3.1