php.net |  support |  documentation |  report a bug |  advanced search |  search howto |  statistics |  random bug |  login
Doc Bug #80794 --enable-bcmath documentation incomplete
Submitted: 2021-02-24 12:02 UTC Modified: 2021-03-07 04:22 UTC
From: php4fan at gmail dot com Assigned:
Status: No Feedback Package: BC math related
PHP Version: Irrelevant OS: all
Private report: No CVE-ID: None
Have you experienced this issue?
Rate the importance of this bug to you:

 [2021-02-24 12:02 UTC] php4fan at gmail dot com
Description:
------------
---
From manual page: https://php.net/bc.installation
---

It says: 
   "These functions are only available if PHP was configured with --enable-bcmath."

So, I look at the output of phpinfo() on a particular installation of phpfpm 7.4 that is throwing "call to undefined function bcpow()" errors and I find:

  Configure Command:
  [.....] '--enable-bcmath=shared' [.....]

So, that's confusing. There is a --enable-bcmath flag, yet the bc math functions are not available, and there is no "BC Math" section in phpinfo(). I guess I need to understand what "shared" means.

For starters, I would expect to find more information at https://www.php.net/manual/en/bc.installation.php
but there's nothing there.

"These functions are only available if PHP was configured with --enable-bcmath.

The Windows version of PHP has built-in support for this extension. You do not need to load any additional extensions in order to use these functions."

The sentence "You do not need to load any additional extensions in order to use these functions" seems to refer only to Windows. What about linux? Do I need to load additional extensions there?

So I think: let's look at the documentation about the "--enable-bcmath" configure flag. Maybe it explains what the value "shared" means. Perhaps it means that it allows to enable bcmath as a shared library-or-something, maybe an extension that can be loaded at runtime without recompiling. I don't know, let's look.

So I found this:

https://www.php.net/manual/en/configure.about.php

"List of configure options".

It's not listed there.

It says:

"Below is a partial list of configure options [...] Most configure options are listed in their appropriate locations on the extension reference pages and not here"

Ok, so where is the "appropriate location on the extension reference pages"??

To me it looks like it should be here:

https://php.net/bc.installation

But again, nothing there.


Patches

Add a Patch

Pull Requests

Add a Pull Request

History

AllCommentsChangesGit/SVN commitsRelated reports
 [2021-02-24 18:33 UTC] requinix@php.net
-Status: Open +Status: Feedback -Package: Documentation problem +Package: BC math related
 [2021-02-24 18:33 UTC] requinix@php.net
What operating system? Linux?

PHP's own installation docs are a little bit lower level than what Linux folks deal with. Here we talk about ./configure and --enable flags because that's what PHP itself is concerned with, but the Linux people who package PHP for distribution will do... whatever it is they do. This often means compiling the base PHP package separately from the various optional extensions, then having the extensions themselves available through package management. You don't ./configure PHP yourself.

So while you are looking to install bcmath, and while the bc.installation page is technically correct, it's not actually the installation information that you need. This is casually mentioned in the general Unix installation docs

> There are several ways to install PHP for the Unix platform, either with a compile
> and configure process, or through various pre-packaged methods. This documentation
> is mainly focused around the process of compiling and configuring PHP.
https://www.php.net/manual/en/install.unix.php

but mostly it's something that's assumed Linux developers are already familiar with.

Make sense?
 [2021-02-24 19:03 UTC] php4fan at gmail dot com
Makes sense, but still...

Of course, I'm not going to recompile PHP, but I want to figure out what it is I need to install. Usually, it is an extension.

So the first thing I look at is 

https://www.php.net/bc.installation

to see if it is an extension that I need to install, or maybe some feature that I need to enable via a runtime configuration option, or what. And note, I don't manage the installation myself, I ask my hosting provider "Please may you install bcmath for me", but before I ask them I try to know at least vaguely what I'm asking them to do.


I would imagine it's an extension, however the first sentence that I find on that documentation page is:

"These functions are only available if PHP was configured with --enable-bcmath."

So, if the only way to enable this extension is via a compile-time configure flag, and obviously I'm not going to recompile php (or ask my hosting provder to do that), that makes me think I need to somehow reinstall PHP, and to get a package that was compiled with that flag.

That seems pretty unlikely. 

So I expected the documentation to explain this a little bit more clearly.

Now that the hosting provider has installed it for me, I see that there actually is a bcmath.so file, and an ini file with an "extension=bcmath" directive.

So that looks an awful lot like an extension, and yet it needs to be configured at compile time? 

Even if I don't need (or want) to compile PHP myself, I think some sort of clarification about what bcmath actually is is not to much to ask from the "installation" section of its documentation.

And if this is explained somewhere else, because it has more to do with how PHP is packaged in a linux distribution than with PHP itself, then I'd expect to find some links.
 [2021-02-24 19:44 UTC] requinix@php.net
"These functions are only available if PHP was configured with --enable-bcmath."

...when you manage your PHP installation yourself. The Linux world does something else (ie, "These functions are only available if the bcmath extension was installed with apt/yum/etc.") and the Windows world mostly does something else ("...if the bcmath extension is enabled/uncommented in php.ini.") and the shared hosting world does yet another thing ("...if the bcmath extension was installed by your hosting provider." or perhaps "...if the bcmath extension was enabled in cPanel.")

The problem is that there are very many ways to set up PHP and its extensions and trying to cover them all in the official docs is an unreasonable burden, but what we can do is cover the fundamental for-people-who-manage-PHP-installations instructions.

Do you have any suggestions for how to describe the various different ways PHP can be set up? Because this is not just about bcmath but about virtually *every* extension - even the so-called "core" ones that the docs say are included will sometimes be *removed* and bundled separately (eg, json).
 [2021-03-07 04:22 UTC] php-bugs at lists dot php dot net
No feedback was provided. The bug is being suspended because
we assume that you are no longer experiencing the problem.
If this is not the case and you are able to provide the
information that was requested earlier, please do so and
change the status of the bug back to "Re-Opened". Thank you.
 
PHP Copyright © 2001-2021 The PHP Group
All rights reserved.
Last updated: Tue Sep 28 19:03:36 2021 UTC