Add __DIR__ path completion capf and php-dot-context primitive

zonuexe · zonuexe · commit 15bb6aceb7f4 · 2026-07-18T04:56:19.000+09:00
Redefine php-complete.el as a small collection of dependency-light,
offline completion-at-point functions usable both as `M-x` commands and
as building blocks for `cape-capf-super'.

* lisp/php.el (php-dot-context): New dependency-free primitive that
  classifies the context before point (`string-or-comment',
  `next-to-string', `code') for context-sensitive `.' insertion, without
  cc-engine.  Meant to drive smartchr/key-combo setups.

* lisp/php-complete.el: State the file's mission in the Commentary.
  (php-complete-complete-function): Redefine as the offline built-in
  function-name source (behavior unchanged).
  (php-complete-path-dir-constants): New option; directory-valued subset
  of `php-magical-constants'.
  (php-complete-complete-path): New capf completing a filesystem path in
  the `__DIR__ . '/...'' idiom, one component at a time, rooted at the
  directory of the current file.  Robust to the unterminated string that
  is normal while typing.

* tests/php-mode-test.el: Cover `php-dot-context' and
  `php-complete-complete-path'.

* README.md, README.ja.md: Document the completion capfs, `cape-capf-super'
  composition, and a `php-dot-context'-based smartchr recipe for `.'.
diff --git a/README.ja.md b/README.ja.md
@@ -86,6 +86,51 @@ M-x package-install php-mode
 
 インデントエンジンはもはやCC Modeを使わないため、`php-mode`では`c-basic-offset`はobsoleteです。かわりに`php-indent-offset`をカスタマイズしてください。後方互換のため、プロジェクトが`c-basic-offset`をバッファローカルに設定している場合(`.dir-locals.el`やファイルローカル変数など)は、`php-mode`がその値を`php-indent-offset`に引き継ぎ、警告を表示します。
 
+## 補完
+
+`php-complete.el`は、言語サーバーなしでも使える依存の軽い小さな`completion-at-point`関数(capf)をいくつか提供します。いずれも`M-x`コマンドとしても、[`cape`][cape]の`cape-capf-super`で合成する部品としても使えます。
+
+- `php-complete-complete-function` — 組み込み関数名。
+- `php-complete-complete-path` — `__DIR__ . '/...'`イディオムの中でパスを補完します。1階層ずつ辿り、起点は現在のファイルのディレクトリ(実行時に`__DIR__`が解決する先)です。
+
+```elisp
+(add-hook 'php-mode-hook
+          (lambda ()
+            (add-hook 'completion-at-point-functions
+                      #'php-complete-complete-path nil t)))
+
+;; …または cape で複数のオフラインソースを1つの super-capf に合成する:
+(add-hook 'php-mode-hook
+          (lambda ()
+            (add-hook 'completion-at-point-functions
+                      (cape-capf-super #'php-complete-complete-function
+                                       #'php-complete-complete-path)
+                      nil t)))
+```
+
+### 文脈依存の `.` キー
+
+`__DIR__`とパス補completionを橋渡しする`. '/'`の挿入は、あえてcapfの仕事にはしていません。これは編集環境側に委ねます。そのための primitive が`php-dot-context`です。ポイントが文字列/コメント内か(`string-or-comment`)、文字列リテラルや`__DIR__`のようなマジック定数の直後か(`next-to-string`)、素のコードか(`code`)を返します。capf とこの primitive は「文字列」と「マジック定数」の定義を共有するため、キー挿入と補completionの挙動が食い違いません。
+
+たとえば[smartchr][smartchr]では、`.`キーをコード中では`->` / `.` / `. `で循環させ、文字列内ではリテラルの`.`を挿入し、`__DIR__`の直後では`. `を優先(そのまま`php-complete-complete-path`につながる)といった設定が書けます。
+
+```elisp
+(defun my-php-smartchr-dot (code within-string next-to-string)
+  "`php-dot-context' を使って `.' キーの smartchr を作る。"
+  (let ((select (lambda ()
+                  (pcase (php-dot-context)
+                    ('string-or-comment within-string)
+                    ('next-to-string    next-to-string)
+                    (_                  code)))))
+    (smartchr-make-struct
+     :cleanup-fn (lambda () (delete-char (- (length (funcall select)))))
+     :insert-fn  (lambda () (insert (funcall select))))))
+
+;; (smartchr (my-php-smartchr-dot "->" "." ". ")
+;;           (my-php-smartchr-dot ". " ".." "..")
+;;           "...")
+```
+
 ## HTMLとPHPが混在するファイルの編集
 
 `php-mode`は純粋なPHPスクリプトのためのメジャーモードです。テンプレートのようにHTMLの中にPHPを埋め込んだファイルは、両方の言語を理解するメジャーモードで編集するほうが適しています。特にインデントは、HTML部分を素の`php-mode`で編集すると正しく動作しません。
@@ -168,9 +213,11 @@ PHP Modeは[GNU General Public License Version 3][gpl-v3] (GPLv3) でライセ
 [Authors]: https://github.com/emacs-php/php-mode/wiki/Authors
 [Contributors]: https://github.com/emacs-php/php-mode/graphs/contributors
 [Supported Version]: https://github.com/emacs-php/php-mode/wiki/Supported-Version
+[cape]: https://github.com/minad/cape
 [cc-mode-manual]: https://www.gnu.org/software/emacs/manual/html_mono/ccmode.html
 [gpl-v3]: https://www.gnu.org/licenses/gpl-3.0
 [per-cs]: https://www.php-fig.org/per/coding-style/
+[smartchr]: https://github.com/imakado/emacs-smartchr
 [#811]: https://github.com/emacs-php/php-mode/issues/811
 [nongnu-elpa-badge]: https://elpa.nongnu.org/nongnu/php-mode.svg
 [nongnu-elpa]: https://elpa.nongnu.org/nongnu/php-mode.html
diff --git a/README.md b/README.md
@@ -88,6 +88,51 @@ The `symfony2` style has been removed, since PER supersedes the coding style use
 
 Because the indentation engine no longer uses CC Mode, `c-basic-offset` is obsolete in `php-mode`; customize `php-indent-offset` instead.  For backward compatibility, when a project sets `c-basic-offset` buffer-locally (for example via `.dir-locals.el` or file-local variables), `php-mode` copies that value into `php-indent-offset` and displays a warning.
 
+## Completion
+
+`php-complete.el` provides a few small, dependency-light `completion-at-point` functions (capfs) for use without a language server.  Each is usable both as an `M-x` command and as a building block for [`cape`][cape]'s `cape-capf-super`:
+
+- `php-complete-complete-function` — built-in function names.
+- `php-complete-complete-path` — a filesystem path inside the `__DIR__ . '/...'` idiom, completed one component at a time and rooted at the directory of the current file (what `__DIR__` resolves to at runtime).
+
+```elisp
+(add-hook 'php-mode-hook
+          (lambda ()
+            (add-hook 'completion-at-point-functions
+                      #'php-complete-complete-path nil t)))
+
+;; …or compose several offline sources into one super-capf with cape:
+(add-hook 'php-mode-hook
+          (lambda ()
+            (add-hook 'completion-at-point-functions
+                      (cape-capf-super #'php-complete-complete-function
+                                       #'php-complete-complete-path)
+                      nil t)))
+```
+
+### A context-sensitive `.` key
+
+Inserting the `. '/'` that bridges `__DIR__` into path completion is deliberately *not* the capf's job; it is left to your editing setup.  `php-dot-context` is the primitive for that: it reports whether point is inside a string or comment (`string-or-comment`), directly after a string literal or a magic constant such as `__DIR__` (`next-to-string`), or in plain code (`code`).  Because the capf and this primitive share the same notion of "string" and "magic constant", key-driven insertion and completion stay consistent.
+
+For example, with [smartchr][smartchr] the `.` key can cycle `->` / `.` / `. ` in code, insert a literal `.` inside strings, and prefer `. ` right after `__DIR__` (which then flows straight into `php-complete-complete-path`):
+
+```elisp
+(defun my-php-smartchr-dot (code within-string next-to-string)
+  "Build a smartchr for the `.' key using `php-dot-context'."
+  (let ((select (lambda ()
+                  (pcase (php-dot-context)
+                    ('string-or-comment within-string)
+                    ('next-to-string    next-to-string)
+                    (_                  code)))))
+    (smartchr-make-struct
+     :cleanup-fn (lambda () (delete-char (- (length (funcall select)))))
+     :insert-fn  (lambda () (insert (funcall select))))))
+
+;; (smartchr (my-php-smartchr-dot "->" "." ". ")
+;;           (my-php-smartchr-dot ". " ".." "..")
+;;           "...")
+```
+
 ## Editing files that mix HTML and PHP
 
 `php-mode` is designed for pure PHP scripts.  Files that embed PHP inside HTML, such as templates, are better edited in a major mode that understands both languages.  Indentation in particular is unreliable when the HTML part of a file is edited in plain `php-mode`.
@@ -169,8 +214,10 @@ This project was maintained by [Eric James Michael Ritz][@ejmr] until 2017. Curr
 [Authors]: https://github.com/emacs-php/php-mode/wiki/Authors
 [Contributors]: https://github.com/emacs-php/php-mode/graphs/contributors
 [Supported Version]: https://github.com/emacs-php/php-mode/wiki/Supported-Version
+[cape]: https://github.com/minad/cape
 [cc-mode-manual]: https://www.gnu.org/software/emacs/manual/html_mono/ccmode.html
 [gpl-v3]: https://www.gnu.org/licenses/gpl-3.0
+[smartchr]: https://github.com/imakado/emacs-smartchr
 [per-cs]: https://www.php-fig.org/per/coding-style/
 [#811]: https://github.com/emacs-php/php-mode/issues/811
 [nongnu-elpa-badge]: https://elpa.nongnu.org/nongnu/php-mode.svg
diff --git a/lisp/php-complete.el b/lisp/php-complete.el
@@ -24,9 +24,23 @@
 
 ;;; Commentary:
 
-;; Provide auto-compiletion functions.
+;; php-complete.el provides a small collection of dependency-light,
+;; offline completion-at-point functions (capfs) for PHP.  It is not an
+;; LSP replacement; it targets the cases an LSP server cannot or will not
+;; handle well.  Each capf is a small, independent unit usable both as an
+;; `M-x' command and as a building block composed with `cape-capf-super':
+;;
+;; - `php-complete-complete-function' -- built-in function name source.
+;; - `php-complete-complete-path'     -- filesystem path inside the
+;;                                       `__DIR__ . '/...'' idiom.
+;;
+;; Key-driven insertion (e.g. a context-sensitive "." key via smartchr)
+;; is intentionally kept out of this file; it belongs to the orthogonal
+;; primitive `php-dot-context'.  Both share the same notion of "string"
+;; and "magic constant", so insertion and completion stay consistent.
 
-;; These functions are copied function from GNU ELPA.
+;; The following helpers are copied from cape.el on GNU ELPA; thanks to
+;; the original author Daniel Mendler (@minad).
 ;;
 ;; - cape--table-with-properties (cape.el)
 ;; - cape--bounds (cape.el)
@@ -52,6 +66,17 @@
                                            php-defs-functions-alist)))
   :safe (lambda (value) (and (listp value) (cl-loop for v in values
                                                     always (assq v php-defs-functions-alist)))))
+
+;;;###autoload
+(defcustom php-complete-path-dir-constants '("__DIR__")
+  "Magic constants treated as the current file directory for path completion.
+
+This is the directory-valued subset of `php-magical-constants' used by
+`php-complete-complete-path'.  Only constants that resolve to a directory
+belong here: \"__DIR__\" qualifies, whereas \"__FILE__\" (a file) does not."
+  :tag "PHP Complete Path Dir Constants"
+  :type '(repeat string)
+  :group 'php-complete)
 
 ;;; Cape functions:
 
@@ -101,7 +126,13 @@ SORT should be nil to disable sorting."
 
 ;;;###autoload
 (defun php-complete-complete-function (&optional interactive)
-  "Complete PHP keyword at point.
+  "Complete a PHP built-in function name at point.
+
+This is the offline built-in function-name source: it offers names from
+the modules listed in `php-complete-function-modules', and is meant for
+environments without an LSP server.  It does not fire after `->' or `::',
+nor after a variable, so it only suggests where a bare function call makes
+sense.
 
 If INTERACTIVE is nil the function acts like a capf."
   (interactive (list t))
@@ -119,5 +150,77 @@ If INTERACTIVE is nil the function acts like a capf."
         :company-kind (lambda (_) 'keyword)
         :exclusive 'no))))
 
+;;; Path completion rooted at `__DIR__':
+
+(defun php-complete--path-directory ()
+  "Return the directory that `__DIR__' resolves to for the current buffer."
+  (or (and buffer-file-name (file-name-directory buffer-file-name))
+      default-directory))
+
+(defun php-complete--path-string-bounds ()
+  "Return (CONTENT-BEG . STR-END) when point is inside a `__DIR__ . STRING'.
+
+CONTENT-BEG is placed after the opening quote and a single leading slash,
+so the path is completed relative to the directory of the current file.
+Return nil when point is not inside such a string.
+
+The recognized directory-valued constants are held in
+`php-complete-path-dir-constants', a subset of `php-magical-constants',
+so this shares its notion of \"magic constant\" with `php-dot-context'."
+  (when (php-in-string-p)
+    ;; Take the string start from `syntax-ppss' (nth 8): it is reliable even
+    ;; for the unterminated string that is normal while typing
+    ;; ("__DIR__ . '/" before the closing quote exists).  Match the preceding
+    ;; "CONST ." with `looking-back' rather than the token scanner, which is
+    ;; not meant to be entered from the opening-quote position.
+    (let ((str-beg (nth 8 (syntax-ppss))))
+      (when (save-excursion
+              (goto-char str-beg)
+              (looking-back
+               (concat (regexp-opt php-complete-path-dir-constants 'symbols)
+                       "[ \t\r\n]*\\.[ \t\r\n]*")
+               (max (point-min) (- str-beg 120))))
+        (let ((content-beg (1+ str-beg)))
+          ;; Keep a single leading "/" fixed so it stays a separator and the
+          ;; path resolves relative to `__DIR__' instead of the filesystem root.
+          (when (eq (char-after content-beg) ?/)
+            (setq content-beg (1+ content-beg)))
+          (cons content-beg
+                (or (ignore-errors
+                      (save-excursion (goto-char str-beg) (forward-sexp) (point)))
+                    (point))))))))
+
+(defun php-complete--path-table ()
+  "Return a file-name completion table rooted at the current file directory.
+The directory is what `__DIR__' resolves to at runtime, bound when the
+table is called rather than captured from the buffer `default-directory'."
+  (let ((dir (php-complete--path-directory)))
+    (lambda (string pred action)
+      (let ((default-directory dir)
+            (non-essential t))
+        (read-file-name-internal string pred action)))))
+
+;;;###autoload
+(defun php-complete-complete-path (&optional interactive)
+  "Complete a filesystem path written as `__DIR__ . \\='/...\\='.'
+
+Inside the string of `__DIR__ . \\='/PATH\\='', complete PATH from the
+directory of the current file, one path component at a time.  This is the
+completion half of the `__DIR__' path idiom; inserting the leading
+`. \\='/\\='' is left to the editor (see `php-dot-context' and the smartchr
+recipe in the README), keeping key-driven insertion and
+completion-at-point orthogonal but consistent.
+
+If INTERACTIVE is nil the function acts like a capf."
+  (interactive (list t))
+  (if interactive
+      (php-complete--cape-interactive #'php-complete-complete-path)
+    (when-let* ((bounds (php-complete--path-string-bounds)))
+      `(,(min (car bounds) (point)) ,(point)
+        ,(php-complete--path-table)
+        :annotation-function ,(lambda (_) " __DIR__ path")
+        :company-kind ,(lambda (_) 'file)
+        :exclusive no))))
+
 (provide 'php-complete)
 ;;; php-complete.el ends here
diff --git a/lisp/php.el b/lisp/php.el
@@ -703,6 +703,32 @@ The order is reversed by calling as follows:
 `find-tag-default' from GNU Emacs etags.el."
   (car (php-leading-tokens 1)))
 
+(defun php-dot-context ()
+  "Classify the context immediately before point for the \".\" key.
+
+Return one of the following symbols:
+
+  `string-or-comment' -- point is inside a string or comment.
+  `next-to-string'    -- the preceding token is a string literal or one of
+                         `php-magical-constants' (for example, point follows
+                         \"__DIR__\"), so a concatenation such as \". \" reads
+                         naturally.
+  `code'              -- anything else.
+
+This is a dependency-free primitive meant to drive context-sensitive
+insertion of the \".\" key with packages such as smartchr or key-combo.
+It shares its notion of \"string\" and \"magic constant\" with
+`php-complete-complete-path', so key-driven insertion and
+completion-at-point stay consistent.  See the README for a recipe."
+  (cond
+   ((php-in-string-or-comment-p) 'string-or-comment)
+   ((when-let* ((token (car (php-leading-tokens 1))))
+      (or (string-prefix-p "'" token)
+          (string-prefix-p "\"" token)
+          (member token php-magical-constants)))
+    'next-to-string)
+   (t 'code)))
+
 ;;; Provide support for Flymake so that users can see warnings and
 ;;; errors in real-time as they write code.
 (defun php-flymake-php-init ()
diff --git a/tests/php-mode-test.el b/tests/php-mode-test.el
@@ -33,6 +33,7 @@
 (require 'php)
 (require 'php-mode)
 (require 'php-project)
+(require 'php-complete)
 (require 'ert)
 (require 'cl-lib)
 (require 'imenu)
@@ -907,6 +908,56 @@ the same logic in an object."
   (with-php-mode-test ("indent/issue-227.php" :indent t :magic t :style pear))
   (with-php-mode-test ("indent/issue-774.php" :indent t :magic t :style pear)))
 
+(ert-deftest php-mode-test-dot-context ()
+  "`php-dot-context' classifies the context immediately before point."
+  (cl-flet ((ctx (code) (with-temp-buffer
+                          (php-mode)
+                          (insert "<?php\n" code)
+                          (php-dot-context))))
+    ;; Preceding a magic constant or a string literal: concatenation reads well.
+    (should (eq 'next-to-string (ctx "__DIR__")))
+    (should (eq 'next-to-string (ctx "__FILE__")))
+    (should (eq 'next-to-string (ctx "'foo'")))
+    (should (eq 'next-to-string (ctx "\"foo\"")))
+    ;; Plain code.
+    (should (eq 'code (ctx "$a")))
+    (should (eq 'code (ctx "foo()")))
+    ;; Inside a string or comment.
+    (should (eq 'string-or-comment (ctx "'foo")))
+    (should (eq 'string-or-comment (ctx "// foo")))))
+
+(ert-deftest php-mode-test-complete-path ()
+  "`php-complete-complete-path' completes the `__DIR__ . \\='/...\\='' idiom."
+  (let* ((root (make-temp-file "php-complete-path" t))
+         (file (expand-file-name "src/App.php" root)))
+    (unwind-protect
+        (progn
+          (make-directory (expand-file-name "src/Controller" root) t)
+          ;; Completes filesystem entries rooted at the file's directory,
+          ;; even when `default-directory' points elsewhere.
+          (with-temp-buffer
+            (php-mode)
+            (setq buffer-file-name file
+                  default-directory temporary-file-directory)
+            (insert "<?php\n$x = __DIR__ . '/")
+            (let ((res (php-complete-complete-path)))
+              (should res)
+              (should (member "Controller/"
+                              (all-completions "" (nth 2 res))))))
+          ;; The leading slash is fixed: BEG sits after "__DIR__ . '/".
+          (with-temp-buffer
+            (php-mode)
+            (setq buffer-file-name file)
+            (insert "<?php\n$x = __DIR__ . '/")
+            (should (eq (car (php-complete--path-string-bounds)) (point))))
+          ;; A plain string is not the idiom.
+          (with-temp-buffer
+            (php-mode)
+            (setq buffer-file-name file)
+            (insert "<?php\n$x = 'plain/")
+            (should-not (php-complete-complete-path))))
+      (delete-directory root t))))
+
 ;; For developers: How to make .faces list file.
 ;;
 ;; 1. Press `M-x eval-buffer' in this file bufffer.
