PermissionsBlock.class.php

Go to the documentation of this file.

<?php
/* Copyright (C) 2026 ATM Consulting <support@atm-consulting.fr>
 * Copyright (C) 2026   MDW       <mdeweerd@users.noreply.github.com>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
require_once DOL_DOCUMENT_ROOT . '/core/lib/functions.lib.php';
 
final class PermissionsBlock
{
  const BEGIN_MARKER = '/* BEGIN MODULEBUILDER PERMISSIONS */';
  const END_MARKER = '/* END MODULEBUILDER PERMISSIONS */';
 
  private const ALLOWED_VARIABLES = array('$this', '$r', '$o');
 
  private const ALLOWED_IDENTIFIERS = array('rights', 'numero', 'sprintf', 'null', 'true', 'false');
 
  private const ALLOWED_PUNCTUATION = array('[', ']', '(', ')', '=', ';', ',', '.', '+', '-', '*');
 
  private const CRUD_OFFSETS = array('read' => 0, 'write' => 1, 'delete' => 2);
 
  private const OBJECT_ID_STRIDE = 10;
 
  private const INDEX_ID = 0;
 
  private const INDEX_LABEL = 1;
 
  private const INDEX_OBJECT = 4;
 
  private const INDEX_CRUD = 5;
 
  private const SUPPORTED_INDEXES = array(0, 1, 4, 5);
 
  private $file;
 
  private $innerBlock;
 
  private function __construct(string $file, string $innerBlock)
  {
    $this->file = $file;
    $this->innerBlock = $innerBlock;
  }
 
  public static function fromFile(string $file): self
  {
    if (strpos($file, '..') !== false) {
      throw new \RuntimeException('Descriptor path must not contain a parent directory reference: '.$file);
    }
    if (!dol_is_file($file)) {
      throw new \RuntimeException('Descriptor file not found: '.$file);
    }
    $content = file_get_contents($file);
    if ($content === false) {
      throw new \RuntimeException('Descriptor file is unreadable: '.$file);
    }
 
    $posBegin = strpos($content, self::BEGIN_MARKER);
    $posEnd = strpos($content, self::END_MARKER);
    if ($posBegin === false || $posEnd === false || $posEnd < $posBegin) {
      throw new \RuntimeException('Cannot find the start and/or end comments of the permissions section in '.$file);
    }
 
    $start = $posBegin + dol_strlen(self::BEGIN_MARKER);
    $innerBlock = dol_substr($content, $start, $posEnd - $start);
 
    return new self($file, $innerBlock);
  }
 
  public function getInnerBlock(): string
  {
    return $this->innerBlock;
  }
 
  public function detectTextConflicts(): array
  {
    $conflicts = array();
    $tokens = token_get_all('<?php '.$this->innerBlock);
 
    foreach ($tokens as $token) {
      if (is_string($token)) {
        if (!in_array($token, self::ALLOWED_PUNCTUATION, true)) {
          $conflicts[] = 'unexpected "'.$token.'" in the permissions block';
        }
        continue;
      }
 
      list($id, $text, $line) = $token;
 
      if (in_array($id, array(T_OPEN_TAG, T_WHITESPACE, T_COMMENT, T_DOC_COMMENT, T_INLINE_HTML), true)) {
        continue;
      }
      if (in_array($id, array(T_LNUMBER, T_DNUMBER, T_CONSTANT_ENCAPSED_STRING, T_OBJECT_OPERATOR, T_INC), true)) {
        continue;
      }
      if ($id === T_VARIABLE) {
        if (!in_array($text, self::ALLOWED_VARIABLES, true)) {
          $conflicts[] = 'line '.$line.': unexpected variable '.$text.' — the permissions block builds its rights dynamically and cannot be rewritten safely';
        }
        continue;
      }
      if ($id === T_STRING) {
        if (!in_array($text, self::ALLOWED_IDENTIFIERS, true)) {
          $conflicts[] = 'line '.$line.': unexpected identifier "'.$text.'" in the permissions block';
        }
        continue;
      }
 
      $conflicts[] = 'line '.$line.': unexpected "'.trim($text).'" in the permissions block — the section cannot be rewritten safely';
    }
 
    return array_values(array_unique($conflicts));
  }
 
  public function detectRightsShapeConflicts(array $permissions): array
  {
    $conflicts = array();
    foreach ($permissions as $i => $right) {
      if (!is_array($right)) {
        $conflicts[] = 'right #'.$i.' is not an array';
        continue;
      }
      if (!isset($right[self::INDEX_OBJECT]) || (string) $right[self::INDEX_OBJECT] === '') {
        $conflicts[] = 'right #'.$i.' declares no object name at index '.self::INDEX_OBJECT;
      }
      if (!isset($right[self::INDEX_CRUD]) || (string) $right[self::INDEX_CRUD] === '') {
        $conflicts[] = 'right #'.$i.' declares no crud code at index '.self::INDEX_CRUD;
      }
    }
 
    return $conflicts;
  }
 
  public function detectRightsShapeWarnings(array $permissions): array
  {
    $warnings = array();
    foreach ($permissions as $i => $right) {
      if (!is_array($right)) {
        continue;
      }
      $unsupported = array_diff(array_keys($right), self::SUPPORTED_INDEXES);
      if (!empty($unsupported)) {
        $warnings[] = 'right #'.$i.' carries unsupported index '.implode(', ', $unsupported).', dropped on rewrite';
      }
    }
 
    return $warnings;
  }
 
  public function render(array $permissions): string
  {
    $grouped = array();
    foreach ($permissions as $right) {
      if (!is_array($right) || !isset($right[self::INDEX_OBJECT], $right[self::INDEX_CRUD])) {
        continue;
      }
      $grouped[(string) $right[self::INDEX_OBJECT]][] = $right;
    }
 
    $lines = array();
    $objectIndex = 0;
    foreach ($grouped as $group) {
      foreach ($this->assignOffsets($group) as $entry) {
        $right = $entry['right'];
        $id = "\$this->numero . sprintf('%02d', (".$objectIndex." * ".self::OBJECT_ID_STRIDE.") + ".$entry['offset']." + 1)";
 
        $lines[] = "\t\t\$this->rights[\$r][".self::INDEX_ID."] = ".$id.";";
        $lines[] = "\t\t\$this->rights[\$r][".self::INDEX_LABEL."] = '".$this->escapeForPhpSingleQuotedString((string) ($right[self::INDEX_LABEL] ?? ''))."';";
        $lines[] = "\t\t\$this->rights[\$r][".self::INDEX_OBJECT."] = '".$this->escapeForPhpSingleQuotedString((string) $right[self::INDEX_OBJECT])."';";
        $lines[] = "\t\t\$this->rights[\$r][".self::INDEX_CRUD."] = '".$this->escapeForPhpSingleQuotedString((string) $right[self::INDEX_CRUD])."';";
        $lines[] = "\t\t\$r++;";
      }
      $objectIndex++;
    }
 
    return empty($lines) ? '' : implode("\n", $lines)."\n";
  }
 
  private function assignOffsets(array $group): array
  {
    $assigned = array();
    $usedOffsets = array();
    $next = count(self::CRUD_OFFSETS);
 
    foreach ($group as $right) {
      $crud = (string) $right[self::INDEX_CRUD];
      if (isset(self::CRUD_OFFSETS[$crud]) && !isset($usedOffsets[self::CRUD_OFFSETS[$crud]])) {
        $offset = self::CRUD_OFFSETS[$crud];
      } else {
        while (isset($usedOffsets[$next])) {
          $next++;
        }
        $offset = $next;
      }
      $usedOffsets[$offset] = true;
      $assigned[] = array('offset' => $offset, 'right' => $right);
    }
 
    usort(
      $assigned,
      static function (array $a, array $b): int {
        return $a['offset'] <=> $b['offset'];
      }
    );
 
    return $assigned;
  }
 
  private function escapeForPhpSingleQuotedString(string $value): string
  {
    return str_replace(array('\\', "'"), array('\\\\', "\\'"), $value);
  }
 
  public function write(string $newInnerBlock): int
  {
    $pattern = '/'.preg_quote(self::BEGIN_MARKER, '/').'.*?'.preg_quote(self::END_MARKER, '/').'/s';
    $replacement = self::BEGIN_MARKER."\n".$newInnerBlock."\t\t".self::END_MARKER;
 
    // preg_replace() reads $1 and \1 in the replacement as backreferences, and a permission
    // label can legitimately contain either.
    $replacement = str_replace(array('\\', '$'), array('\\\\', '\\$'), $replacement);
 
    $result = dolReplaceInFile($this->file, array($pattern => $replacement), '', '0', 0, 1);
    if ($result <= 0) {
      dol_syslog('PermissionsBlock::write failed on '.$this->file.' with code '.$result, LOG_ERR);
      return $result < 0 ? $result : -1;
    }
 
    $this->innerBlock = $newInnerBlock;
 
    return 1;
  }
}