php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #68284 declare encoding docs unclear / encoding handling needs better docs
Submitted: 2014-10-22 09:17 UTC Modified: -
Votes:1
Avg. Score:3.0 ± 0.0
Reproduced:1 of 1 (100.0%)
Same Version:1 (100.0%)
Same OS:1 (100.0%)
From: php-bugs at allenjb dot me dot uk Assigned:
Status: Open Package: Documentation problem
PHP Version: Irrelevant OS:
Private report: No CVE-ID: None
Have you experienced this issue?
Rate the importance of this bug to you:

 [2014-10-22 09:17 UTC] php-bugs at allenjb dot me dot uk
Description:
------------
http://php.net/manual/en/control-structures.declare.php#control-structures.declare.encoding

The documentation for declare encoding is unclear as to what it actually effects. It only says "script encoding", which is, in my opinion, ambiguous.

Is this the encoding in which php source files are presumed to be written? Does it affect anything else such as filesystem functions (file() / fgetcsv(), etc)?

The documentation states the setting is "per script". Does this mean per-source-file, or for an entire script run? Once changed, does the setting apply only to the current file, or to all included / required files too?

Can the setting be changed multiple times, and if so, is there any way to obtain the current value?

The documentation should clearly say what changes this setting invokes and what it affects. It may be useful to explicitly document when developers would want to consider changing this setting.

Specifically it might be useful to document how it differs from:
ini_set('default_charset', 'UTF-8');
mb_internal_encoding("UTF-8");


As a further expansion, it might actually be useful if the manual had a dedicated section on encoding handling (even if most of it is just links to the encoding settings / functions for specific extensions) - especially with some of the features that are looking to make their way into PHP 7. Something like the sections under 'Features', such as 'Connection Handling', that are basically top-level summaries with links to the related manual sections / functions for specifics.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2017-06-18 12:46 UTC] qdinar at gmail dot com
it says : " A script's encoding can be specified per-script using the encoding directive. "

i think i understand this easily:

"Is this the encoding in which php source files are presumed to be written?"

- yes

"Does it affect anything else such as filesystem functions (file() / fgetcsv(), etc)?"

- no

" The documentation states the setting is "per script". Does this mean per-source-file, or for an entire script run? "

- i think that per-source-file

" Once changed, does the setting apply only to the current file, or to all included / required files too? "

- i think that only to the current file

" Can the setting be changed multiple times, and if so, is there any way to obtain the current value? "

- i have found out that it can be first command in file, so i think it can be used once in every file

" Specifically it might be useful to document how it differs from:
ini_set('default_charset', 'UTF-8');
mb_internal_encoding("UTF-8"); "

- i have read at http://php.net/manual/en/ini.core.php#ini.zend.script-encoding : " Literal strings will be transliterated from zend.script_enconding to mbstring.internal_encoding, as if mb_convert_encoding() would have been called. " . - so, i think ini_set and mb_internal_encoding are used when script runs, and  zend.script_encoding , which also can be set with declare(encoding='...'); , is used only for php file. but when i tried to use srings as windows-1251 while php saved as utf-8 , it has not worked, as i see from output with file_put_contents. (i tried to use this because i use one-byte encoding for script's calculations, and want to provide one-byte strings ,  but i want to write php code itself in utf-8 because i use non-windows-1251 characters in comments ). i am going to report this as bug. ... i have tried with swapping windows-1251 and utf-8 and it still does not work. writes "?????" in file in both cases. so i am not sure now, maybe this thing is planned to work in other way.

i see an other documentation problems:

1) are declare encoding and zend.script_encoding working in same and only diference is general or per-file?

2) http://php.net/manual/en/ini.core.php#ini.zend.multibyte says :

" ISO-8859-1 compatible encodings like UTF-8, EUC, etc do not require this option. "

- but it is true only when i do not use the "declare encoding"; when i used it, i have to set it.

3) when i have to set zend.multibyte , i tried ini_set first, but it did not work. seems this is not said in documentation.
 [2017-06-18 16:30 UTC] qdinar at gmail dot com
i have written bug report / feature request for my problem : https://bugs.php.net/bug.php?id=74777 .
 
PHP Copyright © 2001-2018 The PHP Group
All rights reserved.
Last updated: Sun Nov 19 01:31:42 2017 UTC